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PREFACE 


This publication contains descriptions and definitions for the data management macro 
instructions, other than those of VSAM (virtual storage access method), available in the 
assembler language. It provides application and system programmers with the necessary 
information to code the macro instructions. 


Most of the information in this book applies to both OS/VS1 and OS/VS2. Information 
that applies only to OS/VS1 or OS/VS2 is explicitly identified in the text. 


This publication is divided into these parts: 


e “Introduction,” which contains a general description of macro instructions, the rules 
to be followed when macro instructions are coded, and a description of the notational 
conventions used throughout the publication. 


e “Macro Instruction Descriptions,”’ which describes the function of each macro 
instruction and defines how each macro instruction is to be coded. The macro 
instructions are presented in alphabetic order with each macro instruction beginning 
on a right-hand page. The standard form of each macro instruction is described first, 
followed by the description of the list and execute form instructions; the list and 
execute forms are available only for those macro instructions that pass parameters in a 
list. 


¢ “Appendix A: Status Information Following an Input/Output Operation,” which 
includes information about error indications available following an input/output 
operation. 


e “Appendix B: Data Management Macro Instructions Available by Access Method,” 
which lists the macro instructions available for each of the data management access 
methods. 


e« “Appendix C: Device Capacities,’’ which lists device capacities that can be used as a 
guide when coding the block size and logical record length operands in the DCB 
macro instruction. : 


e “Appendix D: DCB Exit List Format and Contents,’’ which describes the format and 
content of the data control block exit list. 


e« “Appendix E: Control Characters,’’ which contains information about the control 
characters used to control spacing and skipping (printers) and stacker selection (card 
read punch or card punch). 


e “Appendix F: Data Control Block Symbolic Field Names,” which lists the location, 
alignment, and description of the data control block symbolic field names. 


e ‘Appendix G: Event Control Block,” which lists the location, alignment, and 
description of the event control block symbolic field names. 


e “Appendix H: PDABD Symbolic Field Names,” which lists the location, alignment 
and description of the PDABD dummy control section. 


e “Index,” which provides topic references to information in this book. 
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Prerequisite Publications 


Before coding data management macro instructions, you should be familiar with the 
information in the following publications: 


OS/VS—DOS/VS—VM/370 Assembler Language, GC33-4010 
OS/VS Data Management Services Guide, GC26-3783 

OS/VSI1 Supervisor Services and Macro Instructions, GC24-5103 
OS/VS2 Supervisor Services and Macro Instructions, GC28-0683 


Related Macro Instruction Publications 


The following publications contain descriptions of macro instructions for VSAM and for 
specialized applications such as teleprocessing, graphics, and magnetic/optical character 
recognition devices: 


OS Data Management Services and Macro Instructions for IBM 
1285/1287/1288, GC21-5004 


OS Data Management Services and Macro Instructions for IBM 1419/1275, 
GC21-5006 


OS and OS/VS Programming Support for the IBM 3505 Card Reader and 
IBM 3525 Card Punch, GC21-5097 


OS/VS BTAM, GC27-6980 


OS/VS Graphic Programming Services (GPS) for IBM 2250 Display Unit, 
GC27-6971 


OS/VS Graphic Programming Services (GPS) for IBM 2260 Display Station 
(Local Attachment), GC27-6972 


OS/VS IBM 3886 Optical Character Reader Model 1 Reference, GC24-5101 


IBM 3890 Document Processor Machine and Programming Description, 
GA24-3612 


OS/VS Virtual Storage Access Method (VSAM) Options for Advanced 
Applications, GC26-3819 


OS/VS Virtual Storage Access Method (VSAM) Programmer’s Guide, GC26-3838 
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Related System Publications 


This book refers to other publications that contain additional information about the 
operating system. Depending on the requirements of the individual installation, an 
application or system programmer may need these publications to code programs for the 
data management access methods. 


In the list that follows, books designated OS/VS apply to both VS1 and VS2; books 
designated OS/VS1 apply only to VS1; and books designated OS/VS2 apply only to 
VS82. 


OS/VS Checkpoint/Restart, GC26-3784 
OS/VS Linkage Editor and Loader, GC26-3813 
OS/VS Utilities, GC35-0005 


OS/VS1 
OS/VS1 
OS/VS1 
OS/VS1 
OS/VS1 
OS/VS1 
OS/VSI1 
OS/VS2 
OS/VS2 
OS/VS2 
OS/VS2 
OS/VS2 


Data Management for System Programmers, GC26-3837 
Debugging Guide, GC24-5093 

JCL Reference, GC24-5099 

JCL Services, GC24-5100 

Supervisor Services and Macro Instructions, GC24-5103 

System Data Areas, SY28-0605 

System Generation Reference, GC26-3791 

JCL, GC28-0692 

Supervisor Services and Macro Instructions, GC28-0683 

System Programming Library: Data Management, GC26-3830 
System Programming Library: Debugging Handbook, GC28-0632 
System Programming Library: System Generation Reference, GC26-3792 
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OS/VS1 SUMMARY OF AMENDMENTS 


Release 4 _ 

New Programming Support 
The IBM 3850 Mass Storage System (MSS) is supported with this release. The MSS 
virtual volumes are functionally equivalent to the 3330/3333 Disk Storage, Model 1. For 
information on MSS, see OS/VS Mass Storage System (MSS) Planning Guide, 
GC35-0011. MSS information is provided for planning purposes only until the system is 
available. 
A new completion code for the BLDL macro has been added. 

Release 3 


New Devices 


e The IBM 3330 Disk Storage (Model 11), IBM 3333 Disk Storage and Control 


(Model 11), and the IBM 3340 Disk Storage are now supported with this release. 
The system also supports the 3420 for Models 4, 6, and 8. 


The IBM 3890 Document Processor and IBM 3886 Optical Character Reader are 


supported with this release. For information on changes to macro instructions for 
these devices, see IBM 3890 Document Processor Machine and Programming 
Description, GA24-3612, or OS/VS IBM 3886 Optical Character Reader Model 
1 Reference, GC24-5101. 


Other Technical Changes 


Editorial Changes 


Reason and return codes are now returned in registers 0 and 15, respectively, for 
BLDL, BSP, FIND, and the STOW macro instructions. 


The PDAB and PDABD macro instructions have been added for QSAM parallel input 
processing. The GET macro instruction for QSAM has also been changed to handle 
parallel input processing. 


The WAIT macro instruction has been added. 
The device capacity tables in Appendix C have been revised. 


Two charts of machine code control characters for printers and card punches have 
been added to Appendix E. 


A new appendix has been added which describes the symbolic field names in the 
PDABD macro instruction (Appendix H). 
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Release 2 


New Devices 


e The 3505 Card Reader and the 3525 Card Punch are now supported by VS1; the 
macro instructions affected by this change are CLOSE, CNTRL, DCB (BSAM and 
QSAM), OPEN, and PRTOV. 


e The 2305-1 Drum Storage and the new 3333 Disk Storage are also now supported by 
VS1; capacity data for these devices has been added to the tables in Appendix C. 


New Function 


e DEB validity checking, a data protection feature formerly supported only by VS2, is 
now supported by VS1; this change affects the OPEN macro instruction. 


Miscellaneous Changes 


e Describe register contents upon entry to an EODAD routine (DCB macro instruction 
for BPAM, BSAM, QISAM, and QSAM). 


¢ Restrict use of the temporary close (TYPE=T) option in a SYNAD routine (CLOSE 
macro instruction). 


e« Expand the description of the LEAVE option (FEOV macro instruction for BsAM 
and QSAM). 


e Define a new return code for the CHKPT macro instruction. 


¢ Delete tape labels as a source of buffer alignment (BFALN) data (DCB macro 
instruction for all access methods). 
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OS/VS2 SUMMARY OF AMENDMENTS 


Release 3 


New Programming Support 


Release 2 


New Devices 


The IBM 3850 Mass Storage System (MSS) is supported with this release. The MSS 
virtual volumes are functionally equivalent to the 3330/3333 Disk Storage, Model 1. For 
information on MSS, see OS/VS Mass Storage System (MSS) Planning Guide, 
GC35-0011. MSS information is provided for planning purposes only until the system is 
available. 


Exchange buffering support was removed for VS2 because it can badly affect 
performance in a virtual system. If exchange buffering is specified, it will be ignored by 
the system. If exchange buffering is denied by the system for any reason, move mode will 
be used instead. Move mode is compatible with exchange buffering. 


Chained scheduling will now be supported by VS2 whether it is requested or not (except 
for printers and format-U input records). This support was changed to improve 
performance in a virtual system. Chained scheduling will not be used where it previously 
was not allowed. 


For QSAM, BUFNO will now default to 5 buffers instead of 2. 


Information for Release 2 is provided for planning purposes only until this system is 
released. 


« The IBM 3330 Disk Storage (Model 11), IBM 3333 Disk Storage and Control 
(Model 11), and the IBM 3340 Disk Storage are supported with this release. 


e« The system also supports the 3420 for Models 4, 6, and 8. 


« The IBM 3890 Document Processor and IBM 3886 Optical Character Reader are 
supported with this release. For information on changes to macro instructions for 
these devices, see JBM 3890 Document Processor Machine and Programming 
Description, GA24-3612, or OS/VS IBM 3886 Optical Character Reader Model 
I Reference, GC24-5101. 


Other Technical Changes 


e« Reason and return codes are now returned in registers 0 and 15, respectively, for 
BLDL, BSP, FIND, and STOW macro instructions. 


e The PDAB and PDABD macro instructions have been added for QSAM parallel input 
processing. The GET macro instruction for QSAM has also been changed to handle 
parallel input processing. 


e The FREE option for the CLOSE macro instruction has been added. 


e Any task sharing a DCB (which it did not open) can now issue the RELEX macro 
instruction to release exclusive control of a data block. 


e Chained scheduling is supported in a virtual address space. 
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Editorial Changes 
e The WAIT macro instruction has been added. 
e The direct-access device capacity tables in Appendix C have been revised. 


e Two charts of machine code control characters for printers and card punches have 
been added to Appendix E. 


e A new appendix has been added which describes the symbolic field names in the 
PDABD macro instruction (Appendix H). 
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INTRODUCTION 


Data Management Macro Instructions 


Coding Aids 


Bold Type 


A set of macro instructions is provided by IBM for communicating service requests to the 
data management access method routines. These macro instructions are available only 
when the assembler language is being used, and they are processed by the assembler 
program using macro definitions supplied by IBM and placed in the macro library when 
the operating system is generated. 


The processing of the macro instruction by the assembler program results in a macro 
expansion, generally consisting of executable instructions and data in the form of 
assembler-language statements. The data fields are the parameters to be passed to the 
access method routine; the executable instructions generally consist of a branch around 
the data fields, instructions to load registers, and either a branch instruction or supervisor 
call (SVC) to give control to the proper program. The exact macro expansion appears as 
a part of the assembler listing. 


A listing of a macro definition from SYS1.MACLIB (the library in which macro 
definitions are stored) can be obtained by using the utility program IEBPTPCH, which is 
described in OS/VS Utilities. 


Before macro instructions are coded using this publication, the user should be familiar 
with the information contained in OS/VS Data Management Services Guide. 


When programs that request supervisor services are being coded, the user should be 
familiar with the information contained in OS/VS1 Supervisor Services and Macro 
Instructions or OS/VS2 Supervisor Services and Macro Instructions. 


When programs are being coded for more specialized applications such as teleprocessing, 
graphics, character recognition, or to use VSAM (virtual storage access method), the 
publication that describes the specific access method and/or device type should be used. 
Publications containing descriptions of the macro instructions for teleprocessing, 
graphics, character recognition devices, and VSAM are listed in the preface of this 
publication. 


The operation of some macro instructions depends on the options selected when the 
macro instruction is coded. For these macro instructions, either separate descriptions are 
provided or the differences are listed within a single description. If no differences are 
explicitly listed, none exist. The description of each macro instruction starts on a 
right-hand page; the descriptions that do not apply to the access methods being used can 
be removed. Appendix B provides a list of the macro instructions available for each 
access method. 


Bold type is used for elements that you must code exactly as they are shown. These 
elements consist of macro names, keywords, and these punctuation symbols: commas, 
parentheses, and equal signs. Examples: 


e DCB 
e CLOSE ,,,. TYPE=T 
e MACRF=(PL,PTC) 
e SK,5 
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Italic Type 


Italic type is used for elements for which you code values that you choose, usually 
according to specifications and limits described for each parameter. Examples: 


e number 
e image-id 


e count 


Brackets 


Brackets, [ ], are used to enclose optional elements, which you may code or not code as 
you choose. Examples: 


¢ [length] 
e [MF=E] 


OR Sign 
The OR sign, | , is used to separate alternative elements. Examples: 
e [,REREAD | ,LEAVE] 
e [length | ‘S’] 


Braces 


Braces, { }, are used to enclose alternative elements for which you must choose exactly 
one element, but never more than one element and never no element. Alternative items 
are usually separated by OR signs. Examples: 


« BFTEK={S|E| A} 
¢ {K|D} 
e« { address |S| 0} 


Sometimes, alternative elements—especially complicated alternatives—are grouped in a 
vertical stack of braces. Examples: 


¢ MACRF= {(R[C| P])} 
i(w[C | P|L)} 
i(R[C],WiC))} 


«e DEVD= {DA 
[ KEYLEN= absexp |} 


iTA 
[,DEN={0|1]2[3] 43] 
|. TRTCH={C|E|ET|T}]} 


iPT 
[,CODE={A|B]C|F|I]N|T3]} 


e {| DA[F] 
DI[F | X] 


DK[F | X] 
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Ellipses 


Underscoring 


Blank Symbol 


In these examples, you must choose exactly one element—one line—from the stack of 
alternative elements. 


Ellipses, ..., indicate that elements may be repeated. Example: 
¢ ( dcbaddr ,|( options), ...) 


Underscored elements indicate those alternative choices that are assumed if you don’t 
make an explicit choice. Examples: 


» HIARCHY={0| 1} 
« BFALN={F|D} 


The blank symbol, 6, is used to indicate the absence of operands. Example: 


jo ppp fe 


Comprehensive Example 


e MF=(E,{ address |(1)}) 


In this example, MF=(E, must be coded exactly as shown. Then, either address or (1) 
must be coded; the parentheses around the 1 are required. Finally, the closing 
parenthesis must be coded. Thus, MF=(E,(1)) might be coded. 


¢ RECFM= {U[T][A | M]} 
iV[B|S|T|BS|BT][A | M]}} 
iD[BI[A]} 
{F[B|S|T|BS|BT][A | M]} 


In this example, the first choice is among the four alternative elements (on four 
separate lines). Then, choices must be made within the major element chosen. 
Assuming that the major element beginning with F were chosen, you would code F; 
then you would choose one of B, S, T, BS, or BT if you liked; and, finally, you would 
choose one of A or M if you liked. Thus, FBTM or FA might be coded. 
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Macro Instruction Format 


Data management macro instructions are written in the assembler language and, as such, 
are subject to the rules contained in OS/VS—-DOS/VS—-VM/370 Assembler Language. 
Data management macro instructions, like all assembler language instructions, are 

written in the following format: 





|Name }| Operation —_| JOperands 


JOperands | Comments 
co Macro name None, one or more operands separated 
by commas 
blank 


The operands are used to specify services and options to be used and are written 
according to the following general rules: 






e If the selected operand is shown in bold capital letters (for example, MACRF= =WL), 
code the operand exactly as shown. 


e If the selected operand is a character string in bold type (for example, if the type 
operand of a READ macro instruction is SF), code the operand exactly as shown. 


e If the operand is shown in italic lowercase letters (for example, dcb address), 
substitute the indicated address, name, or value. 


¢ If the operand is a combination of bold capital letters and italic lowercase letters (for 
example, LRECL=absexp), code the capital letters and equal sign exactly as shown 
and substitute the appropriate address, name, or value for the italic lowercase letters. 


e Commas and parentheses are coded exactly as shown, except that the comma 
following the last operand coded should be omitted. The use of commas and 
parentheses is indicated by brackets and braces in the same manner as brackets and 
braces indicate the use of operands. 


e Several macro instructions contain the designation ‘S’. This operand, when used, must 
have the apostrophe on both sides of the S. 


When substitution of a name, value, or address is required, the notation used to specify 
the operand depends on the operand being coded. The following shows two examples of 
the notations used to indicate how an operand can be coded: 


DDNAME=s=symbol 
In the above example, the only type of operand that can be coded is a valid 
assembler-language symbol. 


dcb address —RX-Type Address, (2-12), or (1) 
In the above example, the operand that can be substituted can be an RX-type address, 
any of the general registers 2 through 12, or general register 1. 


The following describes the meaning of each notation used to show how an operand can 
be coded: 


symbol 
When this notation is shown, the operand can be any valid assembler-language 
symbol. 


decimal digit 
When this notation is shown, the operand can be any decimal digit up to the maximum 
value allowed for the specific operand being described. 
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(2-12) 

When this notation is shown, the operand specified can be any of the general registers 
2 through 12. All registers as operands must be coded in parentheses; for example, if 
register 3 is coded, it is coded as (3). When one of the registers 2 through 12 is used, 
it can be coded as a decimal digit, symbol (equated to a decimal digit), or an 
expression that results in a value of 2 through 12. 


(1) 

When this notation is shown, general register 1 can be used as an operand. When used 
aS an operand in a macro instruction, the register must be specified as the decimal 
digit 1 enclosed in parentheses as shown above. 


(0) 

When this notation is shown, general register 0 can be used as an operand. When used 
aS an operand in a macro instruction, the register must be specified as the decimal 
digit O enclosed in parentheses as shown above. 


RX-Type Address 

When this notation is shown, the operand can be specified as any valid 
assembler-language RX-type address. The following shows examples of each valid 
RX-type address: 


Name Operation Operand 

ALPHAI1 L 1,39(4,10) 

ALPHA2 ly REGI,39(4,TEN) 
BETAI1 L 2,ZETA(4) 

BETA2 LE REG2,ZETA(REG4) 
GAMMAI L 2,ZETA 

GAMMA2 Is REG2,ZETA 
GAMMA3 L 2,=F*° 1000’ 
LAMBDAI1 L 3,20(,5) 


Both ALPHA instructions specify explicit addresses; REG1 and TEN are absolute 
symbols. Both BETA instructions specify implied addresses, and both use index 
registers. Indexing is omitted from the GAMMA instructions. GAMMAI1 and 
GAMMA2 specify implied addresses. The second operand of GAMMAS3 is a literal. 
LAMBDAI specifies an explicit address with no indexing. 


A-Type Address 

When this notation is shown, the operand can be specified as any address that can be 
written as a valid assembler-language A-type address constant. An A-type address 
constant can be written as an absolute value, a relocatable symbol, or relocatable 
expression. Operands that require an A-type address are inserted into an A-type 
address constant during the macro expansion process. For more details about A-type 
address constants, refer to OS/VS—DOS/VS—VM/370 Assembler Language. 


absexp 

When this notation is shown, the operand can be an absolute value or expression. An 
absolute expression can be an absolute term or an arithmetic combination of absolute 
terms. An absolute term can be a nonrelocatable symbol, a self-defining term, or the 
length attribute reference. For more details about absolute expressions, refer to 
OS/VS—DOS/VS—VM/370 Assembler Language. 


relexp 

When this notation is shown, the operand can be a relocatable symbol or expression. 
A relocatable symbol or expression is one whose value changes by n if the program in 
which it appears is relocated n bytes away from its originally assigned area of storage. 
For more details about relocatable symbols and expressions, refer to 
OS/VS—DOS/VS—VM/370 Assembler Language. 
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Rules for Register Usage 


Many macro instruction expansions include instructions that use a base register 
previously defined by a USING statement. The USING statement must establish 
addressability so that macro expansion can include a branch around the in line parameter 
list, if present, and refer to data fields and addresses specified in the macro instruction 
operands. 


Macro instructions that use a BAL or BALR instruction to pass control to an access 
method routine, normally require that register 13 contain the address of an 18-word 
register-save area. The READ, WRITE, CHECK, GET, and PUT macro instructions are 
of this type. : 


Macro instructions that use a supervisor call (SVC) instruction to pass control to an 
access method routine may modify general registers 0, 1, 14, and 15 without restoring 
them. Unless otherwise specified in the macro instruction description, the contents of 
these registers are undefined when the system returns control to the problem program. 


When an operand is specified as a register, the problem program must have inserted the 
value or address to be used into the register as follows: 


e If the register is to contain a value, it must be placed in the low-order portion of the 
register unless the macro instruction description states otherwise. Any unused bits in 
the register should be set to zero. 


e If the register is to contain an address, the address must be placed in the low-order 
three bytes of the register, and the high-order byte of the register should be set to 
Zero. 


Note that if the macro instruction accepts the RX-type address, the high-order byte of a 
register can be efficiently cleared by coding the parameter as O (reg) rather than just 
(reg). Then the macro instruction expands as: 


LA parmreg,O( reg) by macro 
rather than: 
LA reg,0( reg) by user 
and 
LR parmreg,reg by macro 
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Rules for Continuation Lines 

The operand field of a macro instruction can be continued on one or more additional 

lines as follows: | 

1. Enter a continuation character (not blank, and not part of the operand coding) in 
column 72 of the line. 

2. Continue the operand field on the next line, sexu in column 16. All columns to the 
left of column 16 must be blank. 

The operand field being continued can be coded in one of two ways. The operand field 

can be coded through column 71, with no blanks, and continued in column 16 of the next 

line, or the operand field can be truncated by a comma, where a comma normally falls, 


with at least one blank before column 71, and then continued in column 16 of the next 
line. An example of each method is shown in the following illustration: 


Name Operation Operand Comments 

NAME 1 OP 1 OPERAND1 , OPERAND2 , OPERAND3 , OPERAND4 , OPERAND5 , OPERAND6 , OPERAND7 , OPEX 
RAND8& THIS IS ONE WAY 

NAME2 OP2 OPERAND1 ,OPERAND2, THIS IS ANOTHER WAY X 
OPERAND3, X 
OPERAND4 
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BLDL—Build a Directory Entry List (BPAM) 


The BLDL macro instruction is used to complete a list of information from the directory 
of a partitioned data set. The problem program must supply a storage area; the area must 
include information about the number of entries in the list, the length of each entry, and 
the name of each data set member (or alias) before the BLDL macro instruction is 
issued. Data set member names in the list must be in alphameric order. All read and write 
operations using the same data control block must have been tested for completion 
before the BLDL macro instruction is issued. 


The BLDL macro instruction is written as follows: 


[symbol | | BLDL dcb address 
, list address _ 


dcb address—RX-type Address, (2-12), (1), or the decimal digit 0 
The dcb address operand specifies the address of the data control block for an open 
partitioned data set, or zero can be specified to indicate that the data set is in a job 
library, step library, or link library. 


list address —RX-Type Address, (2-12), or (0) 
The list address operand specifies the address of the list to be completed when the 
BLDL macro instruction is issued. The list address must be on a halfword boundary. 
The following illustration shows the format of the list: 


List Oor 
List Description 3 List More 


Address ~ Field Entry (LL bytes) Entries (FF total) 
| ‘ | Sede cer cat eerie fee ere ane” Hae aie Ne eae 


Length» 7 | rae | 
8 3 111 


(bytes) 2 2 
FF: This field must contain a binary value indicating the total number of entries in the 
list. 









USER DATA 





LL: This field must contain a binary value indicating the length, in bytes, of each entry 
in the list (must be an even number of bytes). If the exact length of the entry is 
known, specify the exact length. Otherwise, specify at least 58 bytes (decimal) if the 
list is to be used with an ATTACH, LINK, LOAD, or XCTL macro instruction. The 
minimum length for a list is 12 bytes. 


NAME: This field must contain the member name or alias to be located. The name 
must start in the first byte of the name field and be padded to the right with blanks 
(if necessary) to fill the 8-byte field. | 


When the BLDL macro instruction is executed, five fields of the directory entry list 
are filled in by the system. The specified length (LL) must be at least 14 to fill in the Z 
and C fields. If the LL field is 12, only the NAME, TT, R, and K fields are returned. 
The five fields are: 


TT: Indicates the relative track number where the beginning of the data set member is 
located. 


R: Indicates the relative block (record) number on the track indicated by TT. 


K: Indicates the concatenation number of the data set. For the first or only data set, 
this value is zero. 
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Z: Indicates where the system found the directory entry: 


Code 


0 
l 
2 
3-255 


Meaning 


Private library 

Link library 

Job, task, or step library 

Job, task, or step library of parent task n, where n = Z-2 


C: Indicates the type (member or alias) for the name, the number of note list fields 
(TTRNs), and the length of the user data field (indicated in halfwords). The following 
describes the meaning of the eight bits: 


Bit 
0=0 


Meaning 


Indicates a member name. 

Indicates an alias. 

Indicate the number of TTRN fields (maximum of three) in the user data field. 

Indicate the total number of halfwords in the user data field. If the list entry is to be used 
with an ATTACH, LINK, LOAD, or XCTL macro instruction, the value in bits 3 
through 7 is 22 (decimal). 


USER DATA: The user data field contains the user data from the directory entry. If 
the length of the user data field in the BLDL list is equal to or greater than the user 
data field of the directory entry, the entire user data field is entered into the list. 
Otherwise, the list contains only the user data for which there is space. 


Completion Codes 


When the system returns control to the problem program, the low-order byte of register 
15 contains a return code; the low-order byte of register 0 contains a reason code, as 


follows: 


Hexadecimal Codes 


Return (15) 
00 


04 
08 


08 
OC 


Reason (0) Meaning 


00 Successful completion. 

00 One or more entries in the list could not be filled; the list supplied may be 
invalid. If a search is attempted but the entry is not found, the R field (byte 
11) for that entry is set to zero. 


00 A permanent I/O error was detected when the system attempted to search 
the directory. 

04 Insufficient virtual storage was available. 

00 The DCB for the JOBLIB or STEPLIB DD statement or the DCB specified 


in the TASKLIB parameter of the ATTACH macro was not open (VS1 
only). (if the DCB for the JOBLIB or STEPLIB DD statement was not open, 
this is a system error.) 
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BSP—Backspace a Physical Record (BSAM—Magnetic 


Tape and Direct Access Only) 


The BSP macro instruction causes the current volume to be backspaced one data block 
(physical record). All input and output operations must be tested for completion before 
the BSP macro instruction is issued. The BSP macro instruction should not be used if the 
CNTRL, NOTE, or POINT macro instructions are being used. 


Any attempt to backspace across a file mark will result in a return code of X‘04’ and 
your tape or direct-access volume will not be repositioned. This means you cannot issue a 
successful BSP macro instruction once your EODAD routine is entered unless you first 
reposition the tape or direct-access volume into your data set. (CLOSE TYPE=T would 
get you repositioned at the end of your data set.) 


Magnetic Tape: A backspace is always made toward the load point. 


Direct-Access Device: A BSP macro instruction must not be issued for a data set created 
by using track overflow. 


SYSIN or SYSOUT Data Sets: A BSP macro instruction is ignored, but a completion 
code is returned. 


The BSP macro instruction is written as follows: 


[symbol | BSP dcb address 


dcb address —-RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the 
volume to be backspaced. The data set on the volume to be backspaced must be 
opened before issuing the BSP macro instruction. 


Completion Codes 


When the system returns control to the problem program, the low-order byte of register 
15 contains a return code; the lower-order byte of register 0 contains a reason code, as 


follows: 
Hexadecimal Codes 
Return (15) 
00 00 
04 01 
04 02 
04 03 
04 04 
04 05 
08 


Reason (0) Meaning 


Successful completion. 

A backspacing request was ignored on a SYSIN or SYSOUT data set for VS2 
only. For VS1, this condition results in a return code of 08. 

Backspace not supported for this device type. 

Backspace not successful; insufficient virtual storage was available. 
Backspace not successful; permanent I/O error. 

Backspace into load point or beyond start of data set on the current volume. 
A backspacing request was ignored on a SYSIN or SYSOUT data set for VS1 
only. For VS2, this condition results in a return code of 04. 
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BUILD—Build a Buffer Pool (BDAM, BISAM, BPAM, 
BSAM, QISAM, and QSAM) 


The BUILD macro instruction is used to construct a buffer pool in an area provided by 
the problem program. The buffer pool may be used by more than one data set through 
separate data control blocks. Individual buffers are obtained from the buffer pool using 
the GETBUF macro instruction, and buffers are returned to the buffer pool using a 
FREEBUF macro instruction. Refer to OS/VS Data Management Services Guide for 
an explanation of the interaction of the DCB, BUILD, and GETBUF macro instructions 
in each access method, as well as the buffer size requirements. 


The BUILD macro instruction is written as follows: 


[symbol | | BUILD area address 
s{number of buffers, buffer length | (0)} _ 


area address —RX-Type Address, (2-12), or (1) 
The area address operand specifies the address of the area to be used as a buffer 


pool. The area must start on a fullword boundary. The following illustration shows the 
format of the buffer pool: 


Area 
Address 











Buffer Pool 
Control 
Block 


ff , 
Saye Buffer Buffer 


Length Length 





Buffer 


Buffer 





Area Leneth  -2.2.- = 
Area Length=(Buffer Length) x (Number of Buffers) +8 





number of buffers —symbol, decimal digit, absexp, or (2-12) 
The number-of-buffers operand specifies the number of buffers in the buffer pool up 
to a maximum of 255. 


buffer length—symbol, decimal digit, absexp, or (2-12) 
The buffer length operand specifies the length, in bytes, of each buffer in the buffer 
pool. The value specified for the buffer length must be a fullword multiple; otherwise 
the system rounds the value specified to the next higher fullword multiple. The 
maximum length that can be specified is 32,760 bytes. For QSAM, the buffer length 
must be at least as large as the value specified in the block size (DCBBLKSI) field of 
the data control block. 


Macro Instruction Descriptions: BUILD 31 


(0)—Coded as shown 
The number of buffers and buffer length can be specified in general register 0. If (0) 


is coded, register 0 must contain the binary values for the number of buffers and 
buffer length as shown in the following illustration. 


Register 0 






Buffer Length 





Number of Buffers 





Bits: | 0 31 
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BUILDRCD—Build a Buffer Pool and a Record Area 
(QSAM) | 


The BUILDRCD macro instruction causes a buffer pool and a record area to be 
constructed in a user-provided storage area. This macro is used only for variable-length, 
spanned records processed in QSAM locate mode. Use of this macro before the data set 
is opened, or before the end of the DCBEXIT routine, will automatically invoke a 
logical-record interface rather than a segment interface for variable-length, spanned 
records. 


The standard form of the BUILDRCD macro instruction is written as follows (the list 
and execute forms are shown following the description of the standard form): 















area address 
,number of buffers 
»buffer length 
,record area address 
[,record area length | 


[ symbol | | BUILDRCD 





area address —A-Type Address or (2-12) 
The area address operand specifies the address of the area to be used as a buffer 
pool. The area must start on a fullword boundary. 


number of buffers—symbol, decimal digit, absexp, or (2-12) 
The number of buffers operand specifies the number of buffers, up to a maximum of 
255, to be in the buffer pool. 


buffer length—symbol, decimal digit, absexp, or (2-12) 
The buffer length operand specifies the length, in bytes, of each buffer in the buffer 
pool. The value specified for the buffer length must be a fullword multiple; otherwise, 
the system rounds the value specified to the next higher fullword multiple. The 
maximum length that can be specified is 32,760. 


record area address —A-Type Address or (2-12) 
The record area address operand specifies the address of the storage area to be used 
as a record area. The area must start on a doubleword boundary and have a length of 
the maximum logical record (LRECL) plus 32 bytes. 


record area length—symbol, decimal digit, absexp, or (2-12) 
The record area length operand specifies the length of the record area to be used. 
The area must be as long as the maximum length logical record plus 32 bytes for 
control information. If the record area length operand is omitted, the problem 
program must store the record area length in the first four bytes of the record area. 
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The following illustration shows the format of the buffer pool: 


BUFRECAD 
Address 
of Record Buffer Buffer 
Area 


4 bytes [byte 1 byte 2 bytes 4 bytes [Butter | 


12 bytes 
Buffer Pool Control Block Length 


Area 
Address 











BUFLTH 


Length of 
Each 
Buffer 


BUFLG|BUFNO 









Address of First 
Available Buffer 


Area Length 
Area Length = (Buffer Length) x (Number of Buffers) +12 


BUFLG Flags: 
Bit Meaning 


O= | Record area present 
1=1 Buffer control block extended 
2-7 Reserved 


Notes: 


e The buffer control block contains the address of the record area and a flag that 
indicates logical-record interface processing of variable-length, spanned records. 


e It is the user’s responsibility to release the buffer pool and the record area after a 
CLOSE macro instruction has been issued for all the data control blocks using the 
buffer pool and the record area. 
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BUILDRCD—List Form 


The list form of the BUILDRCD macro instruction is used to construct a program 
parameter list. The description of the standard form of the BUILDRCD macro 
instruction provides the explanation of the function of each operand. The description of 
the standard form also indicates which operands are totally optional and those required 
in at least one of the pair of list and execute forms. The format description below 
indicates the optional and required operands in the list form only. 


The list form of the BUILDRCD macro instruction is written as follows: 










area address 
ynumber of buffers 
»buffer length 
,record area address 
[,record area length | 
JMF=L 


[symbol || BUILDRCD 


area address —A-Type Address 

number of buffers —symbol, decimal digit, or absexp 
buffer length—symbol, decimal digit, or absexp 
record area address —A-Type Address 

record area length—symbol, decimal digit, or absexp 


MF=L—Coded as shown 
The MF=L operand specifies that the BUILDRCD macro instruction is used to create 
a control program parameter list that will be referenced by an execute form 
instruction. 


Note: A control program parameter list can be constructed by coding only the MF=L 
operand (without the preceding comma); in this case, the list is constructed for the area 
address, number of buffers, buffer length, and record area address operands. If the 
record area length operand is also required, the operands can be coded as follows: 


[symbol | BUILDRCD ,,,,0.MF=L 
The preceding example shows the coding to construct a list containing address constants 


with a value of 0 in each constant. The actual values can then be supplied by the execute 
form of the BUILDRCD macro instruction. 
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BUILDRCD-——Execute Form 


A remote control program parameter list is referred to, and can be modified by, the 
execute form of the BUILDRCD macro instruction. The description of the standard form 
of the BUILDRCD macro instruction provides the explanation of the function of each 
operand. The description of the standard form also indicates which operands are totally 
optional and those required in at least one of the pair of list and execute forms. The 
format description below indicates the optional and required operands for the execute 
form only. 


The execute form of the BUILDRCD macro instruction is written as follows: 


[symbol]| BUILDRCD | [area address | 
slnumber of buffers | 


| buffer length | 

sl record area address | 

sLrecord area length | 

sMF=(E,{ control program list address | (1)}) 





area address —RX-Type Address or (2-12) 
number of buffers —absexp 

buffer length—absexp 

record area address —RX-Type Address or (2-12) 
record area length—absexp 


MF=(E,{ control program list address | (1)}) 
This operand specifies that the execute form of the BUILDRCD macro instruction is 
used, and an existing control program parameter list (created by a list-form 
instruction) will be used. The MF= operand is coded as described in the following: 


E—Coded as shown 
control program list address —RX-Type Address, (2-12), or (1) 
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CHECK—wWait for and Test Completion of a Read or 
Write Operation (BDAM, BISAM, BPAM, and BSAM) 


The CHECK macro instruction causes the active task to be placed in the wait condition, 
if necessary, until the associated input or output operation is completed. The input or 
output operation is then tested for errors and exceptional conditions. If the operation is 
completed successfully, control is returned to the instruction following the CHECK 
macro instruction. If the operation is not completed successfully, the error analysis 
(SYNAD) routine is given control or, if no error analysis routine is provided, the task is 
abnormally terminated. The error analysis routine is discussed in the SYNAD operand of 
the DCB macro instruction. 


The following conditions are also handled for BPAM and BSAM only: 


When Reading: The end-of-data (EODAD) routine is given control if an input request is 
made after all the records have been retrieved. Volume switching is automatic for a 
BSAM data set that is not opened for UPDAT. For a BSAM data set that is opened for 
update, the end-of-data routine is entered at the end of each volume. 


When Writing: Additional space on the device is obtained when the current space is filled 
and more WRITE macro instructions have been issued. 


For BPAM and BSAM, a CHECK macro instruction must be issued for each input and 
output operation, and must be issued in the same order as the READ or WRITE macro 
instructions were issued for the data set. For BDAM or BISAM, either a CHECK or 
WAIT macro instruction can be used. 


If the ASCII translation routines are included when the operating system is generated, 
translation can be requested by coding LABEL=(,AL) or (,AUL) in the DD statement, 
or it can be requested by coding OPTCD=Q in the DCB macro instruction or DCB 
subparameter of the DD statement. If translation is requested, the Check routine 
automatically translates BSAM records, as they are read, from ASCII code to EBCDIC 
code, provided that the record format is F, FB, D, DB, or U. Translation occurs as soon 
as the Check routine determines that the input buffer is full. For translation to occur 
correctly, all input data must be in ASCII code. 


The CHECK macro instruction is written as follows: 


[ symbol] | CHECK decb address 
| DSORG={IS | ALL}] 


decb address —RX-Type Address, (2-12), or (1) 
The decb address operand specifies the address of the data event control block 
_created by the associated READ or WRITE macro instruction or used by the 
associated input or output operation. 


DSORG={IS | ALL} 
The DSORG operand specifies the type of data set organization. The following 
describes the characters that can be coded: 


IS 
Specifies that the program generated is for BISAM use only. 


ALL 
Specifies that the program generated is for BDAM, BISAM, BPAM, or BSAM use. 


If the DSORG operand is omitted, the program generated is for BDAM, BPAM, or 
BSAM use only. 
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CHKPT—Take a Checkpoint for Restart Within a Job 
Step (BDAM, BISAM, BPAM, BSAM, QISAM, and 
QSAM) 


The CHKPT macro instruction establishes a checkpoint for the job step. If the step 
terminates abnormally, it is automatically restarted from the checkpoint. On restart, 
execution resumes with the instruction that follows the CHKPT instruction. If the step 
again terminates abnormally (before taking another checkpoint), it is again restarted 
from the checkpoint. When several checkpoints are taken, the step is automatically 
restarted from the most recent checkpoint. 


Automatic restart from a checkpoint is suppressed if: 


1. The job step completion code is not one of a set of codes specified at system 
generation. 


2. The operator does not authorize the restart. 


3. The restart definition parameter of the JOB or EXEC statement specifies no restart 
(RD=NR) or no checkpoint (RD=NC or RD=RNC). 


4. The CANCEL operand appears in the last CHKPT macro instruction issued before 
abnormal termination. 


Under any of these conditions, automatic checkpoint restart does not occur. Automatic 
step restart (restart from the beginning of the job step) can occur, except under 
condition 1 or 2, or when the job step was restarted from a checkpoint prior to abnormal 
termination. Automatic step restart is requested through the restart definition parameter 
of the JOB or EXEC statement (RD=R or RD=RNC). 


When automatic restart is suppressed or unsuccessful, a deferred restart can be requested 
by submitting a new job. The new job can specify restart from the beginning of the job 
step or from any checkpoint for which there is an entry in the checkpoint data set. 


The checkpoint data set contains the information necessary to restart the job step from a 
checkpoint. The control program records this information when the CHKPT macro 
instruction is issued. The macro refers to the data control block for the data set, which 
must be on a magnetic tape or direct-access volume. A tape can have standard labels, 
nonstandard labels, or no labels. 


If the checkpoint data set is not open when CHKPT is issued, the control program opens 
the data set and then closes it after writing the checkpoint entry. If the data set is 
physically sequential and is opened by the control program, the checkpoint entry is 
written over the previous entry in the data set, unless the DD statement specifies 
DISP=MOD. By writing entries alternately into two checkpoint data sets, it is possible to 
keep the entries for the two most recent checkpoints while deleting those for earlier 
checkpoints. 


The data control block for the checkpoint data set must specify: 


DSORG=PS or PO, RECFM=U or UT, MACRF=(W), BLKSIZE= nnn, and 
DDNAME= any name 


where nnn is at least 600 bytes, but not more than 32,760 bytes for magnetic tape and 
not more than the track length for direct access. (If the data set is opened by the control 
program, block size need not be specified; the device-determined maximum block size is 
assumed if no block size is specified.) For seven-track tape, the data control block must 
specify TRTCH=C; for direct access, it must specify or imply KEYLEN=0. To request 
chained scheduling, OPTCD=C and NCP=2 must be specified. With direct access, 
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OPTCD=W can be specified to request validity checking for write operations, and 
OPTCD=WC can be specified to combine validity checking and chained scheduling. 


The standard form of the CHKPT macro instruction is written as follows (information 
about the list and execute forms follows this description): 


[ symbol] | CHKPT ve [,checkid addr|[,checkid length _ 


CANCEL 





dcbaddr 
The dcb address operand specifies the address of the data control block for the 
checkpoint data set. 


checkid address 
The checkid address operand specifies the address of the checkpoint identification 
field. The contents of the field are used when the job step is to be restarted from the 
checkpoint. They are used by the control program in requesting operator authorization 
for automatic restart. You can use it for requesting deferred restart. 


If the next operand specifies the length of the field (checkid length), or if it is omitted 
to imply a length of eight bytes, the field must contain the checkpoint identification 
when the CHKPT macro instruction is issued. If the next operand is written as ‘S’, the 
identification is generated and placed in the field by the control program. If both 
operands are omitted, the control program generates the identification, but does not 
make it available to the problem program. In each case, the identification is written in 
a message to the operator. 


The control program writes the checkpoint identification as part of the entry in the 
checkpoint data set. For a sequential data set, the identification can be any 
combination of up to 16 letters, digits, printable special characters, and blanks. For a 
partitioned data set, it must be a valid member name of up to 8 letters and digits, 
starting with a letter. The identification for each checkpoint should be unique. 


If the control program generates the identification, the identification is 8 bytes in 
length. It consists of the letter C followed by a 7-digit decimal number. The number is 
the total number of checkpoints taken by the job, including the current checkpoint, 
checkpoints taken earlier in the job step, and checkpoints taken by any previous job 
steps. 


checkid length 
The checkid length operand specifies the length in bytes of the checkpoint 
identification field. The maximum length is 16 bytes if the checkpoint data set is 
physically sequential, 8 bytes if it is partitioned. For a partitioned data set, the field 
can be longer than the actual identification, if the unused portion is blank. If the 
operand is omitted, the implied length is 8 bytes. 


If you code ‘S’ the control program supplies the checkpoint identification. The implied 
field length is 8 bytes. 


CANCEL 
The CANCEL operand cancels the request for automatic restart from the most recent 
checkpoint. If another checkpoint is taken before abnormal termination, the job step 
can be restarted at that checkpoint. 
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When control is returned, register 15 contains one of the following return codes: 


Hexadecimal Meaning 


Code 
00 


04 


08 


0C 


10 


14 


Successful completion. Code 00 is also returned if the RD parameter was coded as 
RD=NC or RD=RNC to totally suppress the function of CHKPT. 


Restart has occurred at the checkpoint taken by the CHKPT macro instruction during the 
original execution of the job. A request for another restart of the same checkpoint is 
normally in effect. If a deferred restart was performed and RD=NC, NR, or RNC was 
specified in the resubmitted deck, a request for another restart is not in effect. 


Unsuccessful completion. A checkpoint entry was not written, and a restart from this 
checkpoint was not requested. A request for an automatic restart from a previous 
checkpoint remains in effect. 


One of the following conditions exists: 
« The parameters passed by the CHKPT macro instruction are invalid. 


e The CHKPT macro instruction was executed in an exit routine other than the 
end-of-volume exit routine. 


e ASTIMER macro instruction has been issued, and the time interval has not been 
completed. 


¢ A WTOR macro instruction has been issued, and the reply has not been received. 


« The checkpoint data set is on a direct-access volume and is full. Secondary space 
allocation was requested and performed. (Secondary space allocation is performed for 
a checkpoint data set, but the allocated space is not used. However, had secondary 
allocation not been requested, the job step would have been abnormally terminated.) 


¢ A graphics-type DSORG has been found in an open DCB. Graphic devices are not 
supported in checkpoint/restart. 


« The job step contains more than one task. 


Unsuccessful completion. An uncorrectable error occurred in writing the checkpoint entry 
or in completing queued access method input/output operations that were begun before 
the CHKPT macro instruction was issued. A partial, invalid checkpoint entry may have 
been written. If the entry has a programmer-specified checkid, and the checkpoint data 
set is sequential, a different checkid should be specified the next time CHKPT is executed. 
If the data set is partitioned, a different checkid need not be specified. This code is also 
returned if the checkpoint routine tries to open the checkpoint data set and the DD 
statement for the data set is missing. 


Successful completion with possible error condition. The task has control, by means of an 
explicit or implied use of the ENQ macro instruction, of a serially reusable resource; if the 
task terminates abnormally, it will not have control of the resource when the job step is 
restarted. The user’s program must, therefore, reissue the ENQ macro instruction. 


Checkpoint not taken. End of volume occurred while writing the checkpoint entry on a 
tape data set. The checkpoint was canceled, but processing of the user’s program 
continues. 


When one of the errors indicated by code 08, OC, 10, or 14 occurs, the system prints an 
error message on the operator’s console. The message indicating code 08 or OC contains 
a code that further identifies the error. The operator should report the message contents 
to the programmer. 


Note: Successful use of the CHKPT macro instruction requires some care in the selection 
of checkpoints. For a detailed discussion of checkpoint requirements, refer to OS/VS 
Checkpoint/ Restart. 
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CHKPT—List Form 


The list form of the CHKPT instruction is used to construct a control program parameter 
list. 


The description of the standard form of the CHKPT macro provides the explanation of 
the function of each operand. The description of the standard form also indicates which 
operands are optional and which are required in at least one of the list and execute 
forms. The format description below indicates the optional and required operands in the 
list form only. Note that the CANCEL operand, which can be coded in the standard 
form, cannot be coded in the list form. 


The list form of the CHKPT macro instruction is written as follows: 









{ symbol | | CHKPT [dcb address | 
| checkid address | 
yLcheckid length | ‘S’| 
MF=L 
address 

The address operand specifies any address that may be written in an A-type address 
constant. 


length 
The length operand specifies any absolute expression that is valid in the assembler 
language. 

MF=L 
The MF=L operand indicates the list form of the CHKPT macro instruction. 
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CHKPT—Execute Form 


A control program parameter list is referred to, and can be modified by, the execute form 
of the CHKPT macro. 


The description of the standard form of the CHKPT macro provides the explanation of 
the function of each operand. The description of the standard form also indicates which 
operands are optional and which are required in at least one of the list and execute 
forms. The format description below indicates the optional and required operands for the 
execute form only. Note that the CANCEL operand, which can be coded in the standard 
form, cannot be coded in the execute form. 


The execute form of the CHKPT macro instruction is written as follows: 


[symbol] | CHKPT [dcb address | 
sl checkid address | 


sLcheckid length | ‘S’] 
sMF=(E,{ control program list address | (1)}) 





address 
The address operand specifies any address that is valid in an RX-type instruction, or 
one of the general registers 2 through 12, previously loaded with the indicated 
address. You may designate the register symbolically or with an absolute expression; 
always code it in parentheses. : 


length | 
The length operand specifies any absolute expression that is valid in assembler 
language, or one of the general registers 2 through 12, previously loaded with the 
indicated value. You may designate the register symbolically or with an absolute 
expression; always code it in parentheses. _ 


MF=(E,{ control program list address | (1)}) 
This operand specifies the execute form of the macro instruction using a control 
program parameter list. The address of the control program parameter list can be 
coded as described under address, or can be loaded into register 1, in which case code 
MF=(E,(1)). 
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CLOSE—Logically Disconnect a Data Set (BDAM, 
BISAM, BPAM, BSAM, QISAM, and QSAM) 


The CLOSE macro instruction causes output data set labels to be created, and volumes 
to be positioned as specified by the user. The fields of the data control block are restored 
to the condition that existed before the OPEN macro instruction was issued, and the data 
set is disconnected from the processing program. Final volume positioning for the current 
volume can be specified to override the positioning implied by the DD control statement 
DISP parameter. Any number of dcb address operands and associated options may be 
‘specified in the CLOSE macro instruction. 


Associated data sets for a 3525 card punch can be closed in any sequence, but if one 
data set is closed, I/O operations cannot be initiated for any of its associated data sets. 
Additional information about closing associated data sets is contained in OS/VS Data 
Management Services Guide. 


A FREEPOOL macro instruction should normally follow a CLOSE macro instruction 
(without TYPE=T) to regain the buffer pool storage space and to allow a new buffer 
pool to be built if the DCB is reopened with different record size attributes. 


A special operand, TYPE=T, is provided for processing with BSAM. 


The standard form of the CLOSE macro instruction is written as follows (the list and 
execute forms are shown following the description of the standard form): 


[ symbol ] | CLOSE (dcb address ,| option |, ...) 
[,TYPE=T] 





dcb address —A-Type Address or (2-12) 
The dcb address operand specifies the address of the data control block for the 
opened data set that is to be closed. 


option 
One of these options indicate the volume positioning that is to occur when the data set 
is closed. The option operand is ignored for ISAM, BDAM, SYSIN, and SYSOUT 
data sets and also for data sets on other than magnetic tape or direct-access devices. If 
the option specified is FREE, this operand is not ignored for BDAM, SYSIN, and 
SYSOUT data sets. The options are: 


REREAD 
Specifies that the current volume is to be positioned to reprocess the data set. If 
processing was forward, the volume is positioned to the beginning of the data set; if 
processing was backwards (RDBACK), the volume is positioned to the end of the 
data set. | 


LEAVE 
Specifies that the current volume is to be positioned to the logical end of the data 
set. If processing was forward, the volume is positioned to the end of the data set; 
if processing was backwards (RDBACK), the volume is positioned to the beginning 
of the data set. 

REWIND 
Specifies that the current magnetic tape volume is to be positioned at the load 
point, regardless of the direction of processing. REWIND cannot be specified when 
TYPE=T is specified. In VS2 systems, if FREE=CLOSE has been coded on the 
DD statement associated with the data set being closed, coding the REWIND 
option will result in the data set being freed at the time it is closed rather than at 
the termination of the job step. 
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FREE 
For VS2 systems only, specifies that the current data set is to be freed at the time 
the data set is closed, rather than at the time the task is terminated. For tape data 
sets, this means that the volume is eligible for use by other tasks or to be 
demounted. Direct-access volumes may also be freed for use by other tasks. They 
may be freed for demounting if (1) no other data sets on the volume are open and 
(2) the volume is otherwise demountable. Do not use this option with CLOSE 
TYPE=T. 


DISP 
Specifies that a tape volume is to be disposed of in the manner implied by the DD 
statement associated with the data set. Direct-access volume positioning and 
disposition are not affected by this parameter of the CLOSE macro instruction. 
There are several dispositions that can be specified in the DISP parameter of the 
DD statement; DISP can be PASS, DELETE, KEEP, CATLG, or UNCATLG. 


VS1 Systems: Depending on how the DISP option is coded in the DD statement, 
the current magnetic tape volume will be positioned as follows: 


DISP Parameter Action 

PASS Forward space to the end of data set on the current 
volume. 

DELETE Rewind the current volume. 

KEEP, CATLG, or UNCATLG Rewind and unload the current volume. 


VS2 Systems: Depending on how the DISP option is coded in the DD statement, 
the current magnetic tape volume will be positioned as follows: 


DISP Parameter Action 

PASS Forward space to the end of the data set on the current 
volume. 

DELETE | Rewind the current volume. 

KEEP, CATLG, or UNCATLG The volume is positioned the same as for CLOSE 
REREAD. Note that the volume is not rewound and 
unloaded. 


In VS2 systems, if FREE=CLOSE has been coded in the DD statement associated 
with this data set, coding the DISP option in the CLOSE macro will result in the 
data set being freed when the data set is closed, rather than at the time the job step 
is terminated. 


Note: When the option operand is omitted, DISP is assumed. For TYPE=T, this is 
processed as LEAVE during execution. 


The LEAVE and REREAD options are meaningless except for magnetic tape and 
CLOSE TYPE=T. 


TYPE=T—Coded as shown 
You can code CLOSE TYPE=T and temporarily close sequential data sets on 
magnetic tape and direct-access volumes processed with BSAM. When you use 
TYPE=T, the DCB used to process the data set maintains its open status, and you 
don’t have to issue another OPEN macro instruction to continue processing the same 
data set. This option cannot be used in a SYNAD routine nor can it be used in 
conjunction with the FREE option. 


A request to temporarily close a data set causes the system control program to process 
labels, modify some of the fields in the system control blocks for that data set, and 
reposition the volume (or current volume in the case of multivolume data sets) in 
much the same way that the normal CLOSE macro does. When you code TYPE=T, 
you can specify that the volume either be positioned at the end of data (the LEAVE 
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option) or be repositioned at the beginning of data (the REREAD option). 
Magnetic-tape volumes are repositioned either immediately before the first data 
record or immediately after the last data record; the presence of tape labels has no 


effect on repositioning. 


| If you code the release (RLSE) operand on the DD statement for an output data set, 
it is ignored by temporary close (CLOSE TYPE=T), but any unused space will be 
released when you finally issue the normal CLOSE (without TYPE=T) macro 


instruction. 
Refer to OS/VS Data Management Services Guide for additional information and 
coding restrictions. 


6" 
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CLOSE—List Form 


The list form of the CLOSE macro instruction is used to construct a data management 
parameter list. Any number of operands (data control block addresses and associated 
options) can be specified. 


The list consists of a one-word entry for each DCB in the parameter list; the high-order 
byte is used for the options and the three low-order bytes are used for the DCB address. 
The end of the list is indicated by a one in the high-order bit of the last entry’s option 
byte. The length of a list generated by a list-form instruction must be equal to the 
maximum length required by an execute-form instruction that refers to the same list. A 
maximum length list can be constructed by one of two methods: 


e Code a list-form instruction with the maximum number of parameters that are 
required by an execute-form instruction that refers to the list. 


« Code a maximum length list by using commas in a list-form instruction to acquire a list 
of the appropriate size. For example, coding CLOSE (,,,,,,,,,), MF=L would provide a 
list of five fullwords (five dcb addresses and five options). 


Entries at the end of the list that are not referenced by the execute-form instruction are 
assumed to have been filled in when the list was constructed or by a previous 
execute-form instruction. Before using the execute-form instruction, you may shorten the 
list by placing a one in the high-order bit of the last DCB entry to be processed. 


A zeroed work area on a word boundary is equivalent to CLOSE (,DISP.,...),MF=L and 
can be used in place of a list-form instruction. The high-order bit of the last DCB entry 
must contain a one before this list can be used with the execute-form instruction. 


A parameter list constructed by a CLOSE macro instruction, list form, can be referred to 
by either an OPEN or CLOSE execute-form instruction. 


The description of the standard form of the CLOSE macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are completely optional and those required in at least one of 
the pair of list and execute forms. The format description below indicates the optional 
and required operands in the list form only. 


The list form of the CLOSE macro instruction is written as follows: 


[ symbol | | CLOSE ([dcb address |,| option |, ...) 
[ TYPE=T]| 
MF=L 





dch address —A-Type Address 
option —Same as standard form 


TYPE=T—Coded as shown 
The TYPE=T operand can be coded in the list-form instruction to allow the specified 
option to be checked for validity when the program is assembled. 


MF=L—Coded as shown 
The MF=L operand specifies that the CLOSE macro instruction is used to create a 
data management parameter list that will be referred to by an execute-form 
instruction. 
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CLOSE—Execute Form 


A remote data management parameter list is used in and can be modified by the execute 
form of the CLOSE macro instruction. The parameter list can be generated by the list 
form of either an OPEN macro instruction or a CLOSE macro instruction. 


The description of the standard form of the CLOSE macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are totally optional and those required in at least one of the 
pair of list and execute forms. The format description below indicates the optional and 
required operands in the execute form only. 


The execute form of the CLOSE macro instruction is written as follows: 


[ symbol | | CLOSE [({dcb address |,| option |, ...)] 
[| .TYPE=T] 
JMF=(E,{ data management list address | (1)}) 





dcb address-—-RX-Type Address or (2-12) 
option —Same as standard form 
TYPE=T—Same as standard form 


MF=(E,{ data management list address | (1)}) 
This operand specifies that the execute form of the CLOSE macro instruction is being 
used, and an existing data management parameter list (created by a list-form 
instruction) will be used. The MF= operand is coded as described in the following: 


E—Coded as shown 
data management list address —-RX-Type Address, (2-12), or (1) 
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CNTRL—Control Online Input/Output Device (BSAM 
and QSAM) 


The CNTRL macro instruction is used to control magnetic tape drives (BSAM only for a 
data set that is not open for output), online card readers, 3525 card punches (read and 
print features, VS2 only), printers (BSAM and QSAM), the 3886 Optical Character 
Reader (BSAM only), and the 3890 Document Processor (QSAM only). For information 
on additional operands for the CNTRL macro instruction for the 3886 and 3890, see 
OS/VS IBM 3886 Optical Character Reader Model 1 Reference and IBM 3890 
Document Processor Machine and Programming Description. 


For information on additional operands for the CNTRL macro for the 1275 or 1419, see 
OS Data Management Services and Macro Instructions for IBM 1419/1275. 


The MACREF operand of the DCB macro instruction must specify a C. The CNTRL 
macro instruction is ignored for SYSIN or SYSOUT data sets. For BSAM, all input and 
output operations must be tested for completion before the CNTRL macro instruction is 
issued. The control facilities available are as follows: 


Card Reader: Provides stacker selection, as follows: 


QSAM—The CNTRL macro instruction is issued whenever it is necessary to read a new 
card. For unblocked records, a CNTRL macro instruction should be issued after every 
input request. For blocked records, a CNTRL macro instruction is issued after the last 
logical record on each card that is retrieved. The move mode of the GET macro 
instruction must be used, and the number of buffers (BUFNO field of the DCB) must be 
one. 


BSAM—The CNTRL macro instruction should be issued after every input request. 


Printer: Provides line spacing or a skip to a specific carriage control channel. A CNTRL 
macro instruction cannot be used if carriage control characters are provided in the 
record. If the printer contains the universal character set feature, data checks should be 
blocked (OPTCD=U should not appear in the data control block). 


Magnetic Tape: Provides method of forward spacing and backspacing (BSAM only for a 
data set that is not open for output). If OPTCD=H is indicated in the data control block, 
the CNTRL macro instruction can be used to perform record positioning on DOS tapes 
that contain embedded checkpoint records. Embedded checkpoint records encountered 
during the record positioning are bypassed and are not counted as blocks spaced over. 
OPTCD=H must be specified in a job control language DD statement. The CNTRL 
macro instruction cannot be used to backspace DOS 7-track tapes that are written in 
data convert mode that contain embedded checkpoint records (BSAM). 


Note: The CNTRL macro should not be used with output operations on BSAM tape data 
sets. 


3525 Printing: Provides line spacing or a skip to a specific printing line on the card. The 
card contains 25 printing lines; the odd numbered lines 1 through 23 correspond to the 
printer skip channels 1 through 12 (see the SK operand). For additional information 
about 3525 printing operations, refer to OS and OS/VS Programming Support for 
the IBM 3505 Card Reader and IBM 3525 Card Punch. 
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| 
The CNTRL macro instruction is written as follows: 


[symbol | | CNTRL dcb address 
SS, {1 | 2} 


SP,{1| 2/3} 


99K, {1 | 2]... | 11] 12} 


»BSR[, number of blocks | 
FSR[,number of blocks | 


‘deb address 
| The dcb address operand specifies the address of the data control block for the data 


set opened for the online device. 


SS, {1 | 2} 
| The SS operand is coded as shown to indicate that the control function requested is 
stacker selection on a card reader; either 1 or 2 must be coded to indicate which 


stacker is to be selected. 


| 
'SP,{1 | 2 | 3} 

| b 

| The SP operand is coded as shown to indicate that the control function requested is 

| printer line spacing or 3525 card punch line spacing; either 1, 2, or 3 must be coded to 


indicate the number of spaces for each print line. 


'SK,{1[2|...| 11112} 

' The SK operand is coded as shown to indicate that the control function requested is a 
skip operation on the printer or 3525 card punch, print feature; a number (1 through 
12) must be coded to indicate the channel or print line to which the skip is to be 


taken. 


| 
| BSM—Coded as shown 

The BSM operand indicates that the control function requested is to backspace the 
| magnetic tape past a tapemark, then forward space over the tapemark. When this 
operand is specified, the DCBBLKCT field in the data control block is set to zero. 
| 


FSM—Coded as shown 
| The FSM operand indicates that the control function requested is to forward space the 
| magnetic tape over a tapemark, then backspace past the tapemark. When this operand 
is specified, the DCBBLKCT field in the data control block is set to zero. 


The BSR operand indicates that the control function requested is to backspace the 


BSR—Coded as shown 

| magnetic tape the number of blocks indicated in the number-of-blocks operand. 
| 
| 


FSR—Coded as shown 
The FSR operand indicates that the control function requested is to forward space the 
magnetic tape the number of blocks indicated in the number-of-blocks operand. 
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number of blocks —symbol, decimal digit, absexp, or (2-12) 
The number-of-blocks operand specifies the number of blocks to backspace (see 
BSR operand) or forward space (see FSR operand) the magnetic tape. The 
maximum value that can be specified is 32,767. If the number-of-blocks operand is 
omitted, one is assumed. 


If the forward space or backspace operation is not completed successfully, control is 
passed to the error analysis (SYNAD) routine; if no SYNAD routine is designated, the 
task is abnormally terminated. Register contents, when control is passed to the error 
analysis routine, are shown in Appendix A. If a tapemark is encountered for BSR or 
FSR, control is returned to the processing program, and register 15 contains a count of 
the uncompleted forward spaces or backspaces. If the operation is completed normally, 
register 15 contains the value zero. 
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DCB—cConstruct a Data Control Block (BDAM) 


The data control block for a basic direct access method (BDAM) data set is constructed 
during assembly of the problem program. The DCB macro instruction must not be coded 
within the first 16 bytes of addressability for the control section (CSECT). The DSORG 
and MACRF operands must be coded in the DCB macro instruction, but the other 
operands can be supplied from other sources. Each of the BDAM DCB operand 
descriptions contains a heading, “Source.” The information under this heading describes 
the sources from which an operand can be supplied to the data control block. 


Before a DCB macro instruction for a BDAM data set is coded, the following 
characteristics of direct data sets should be considered: 


e The problem program must synchronize I/O operations by issuing a CHECK or 
WAIT macro instruction to test for completion of read and write operations. 


¢« A BDAM data set is created using the basic sequential access method (BSAM). A 
special operand (MACRF=WL) specifies that BSAM is being used to create a BDAM 
data set. Operand descriptions for the BDAM DCB macro instruction include 
information about both creating and processing a BDAM data set. 


e Although a BDAM data set can contain blocked records, the problem program must 
perform all blocking and deblocking of records. BDAM provides only the capability to 
read or write a data block, but the data block can contain multiple logical records 

_ assembled by the problem program. 


e When a BDAM data set is being created, buffers can be acquired automatically, but 
buffer control must be provided by the problem program. The problem program must 
place data in the output buffer before issuing a WRITE macro instruction to write the 
data block. 


¢ When a BDAM data set is being processed, the problem program can control all 
buffering, or dynamic buffering can be specified in the DCB macro instruction and 
subsequently requested in a READ macro instruction. 


» The actual organization of a direct data set is determined by the programmer to meet 
the needs of the application. The data set can be processed by using one of the 
following addressing methods: 


» Actual device addresses (in the form MBBCCHHR). 


‘ Relative track addresses (in the form TTR). These addresses specify a track (and a 
record on the track) of the direct-access device relative to the beginning of the data 
set. 


e Relative block addresses can be used with fixed-length records. These addresses 
specify a data block relative to the beginning of the data set. 


For additional information about the characteristics of BDAM data sets, refer to OS/VS 
Data Management Services Guide. 
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The DCB macro for BDAM is written as follows: 


[symbol] | DCB [BFALN={F | D}] 
[BFTEK=R] 
[BLKSIZE= absexp | 
[BUFCB= relexp | 
[BUFL= absexp | 
[BUFNO= absexp | 
[DDNAME= symbol }! 
DSORG={DA | DAU} 
[EXLST= relexp | 


[KEYLEN= absexp | | 
[LIMCT= absexp ] 


MACRF= {(R{K(I] | T[X][S}LC})$ 
{(W{ATKI(T] | KW) | [C])} 
{(R{K(T) | UEXILSILC],W{ALK][T] | KUT) | 13[C))} 


[OPTCD=[R | A][E][F][W]] 
[RECFM={U | V[S | BS] | F[T]}] 
[SYNAD= relexp |] 





1 This parameter must be supplied before an OPEN macro is issued for this DCB; 

it cannot be supplied in the open exit routine. 
The following describes the DCB operands that can be specified for creating and 
processing a BDAM data set: 


BFALN={F | D} 
The BFALN operand specifies the boundary alignment for each buffer in the buffer 
pool. The BFALN operand can be specified when (1) BSAM is being used to create a 
BDAM data set and buffers are acquired automatically, (2) when an existing BDAM 
data set is being processed and dynamic buffering is requested, or (3) when the 
GETPOOL macro instruction is used to construct the buffer pool. If the BFALN 
operand is omitted, the system provides doubleword alignment for each buffer. The 
following describes the characters that can be specified: 


F 
Specifies that each buffer is aligned on a fullword boundary that is not also a 
doubleword boundary. 


D 
Specifies that each buffer is aligned on a doubleword boundary. 


If the BUILD macro instruction is used to construct the buffer pool or if the problem 
program controls all buffering, the problem program must provide the area for the 
buffers and control buffer alignment. 


Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFALN and BFTEK operands are 
specified, they must be supplied from the same source. 


BFTEK=R 
The BFTEK operand specifies that the data set is being created for or contains 
variable-length spanned records. The BFTEK operand can be coded only when the 
record format is specified as RECFM=VS. 


When variable-length spanned records are written, the data length can exceed the 
total capacity of a single track on the direct-access device being used, or it can exceed 
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the remaining capacity on a given track. The system divides the data block into 
segments (if necessary), writes the first segment on a track, and writes the remaining 
segment(s) on the following track(s). 


When a variable-length spanned record is read, the system reads each segment and 
assembles a complete data block in the buffer designated in the area address operand 
of a READ macro instruction. 


Note: Variable-length spanned records can also be read using BSAM. When BSAM is 
used to read a BDAM variable-length spanned record, the record is read one segment 
at a time, and the problem program must assemble the segments into a complete data 
block. This operation is described in the section for the BsAM DCB macro 
instruction. 


Source: The BFTEK operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFTEK and BFALN operands are 
specified, they must be supplied from the same source. 


BLKSIZE=absexp (maximum value is 32,760) 
The BLKSIZE operand specifies the length, in bytes, of each data block for 
fixed-length records, or it specifies the maximum length, in bytes, of each data block 
for variable-length or undefined-length records. If keys are used, the length of the key 
is not included in the value specified for the BLKSIZE operand. 


The actual value that can be specified in the BLKSIZE operand depends on the record 
format and the type of direct-access device being used. If the track-overflow feature is 
being used or if variable-length spanned records are being used, the value specified in 
the BLKSIZE operand can be up to the maximum. For all other record formats (F, V, 
VBS, and U), the maximum value that can be specified in the BLKSIZE operand is 
determined by the track capacity of a single track on the direct-access device being 
used. Device capacity for direct-access devices is described in Appendix C of this 
publication. For additional information about device capacity and space allocation, 
refer to OS/VS Data Management Services Guide. 


Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 


BUFCB=relexp 
The BUFCB operand specifies the address of the buffer pool control block when the 
buffer pool is constructed by a BUILD macro instruction. 


If the buffer pool is constructed automatically, dynamically, or by a GETPOOL macro 
instruction, the system places the address of the buffer pool control block into the 
data control block, and the BUFCB operand is not required. The BUFCB operand is 
not required if the problem program controls all buffering. 


Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


BUFL=absexp (maximum value is 32,760) 
The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool 
when the buffers are acquired automatically (create BDAM) or dynamically (existing 
BDAM). 


When buffers are acquired automatically (create BDAM), the BUFL operand is 
optional; if specified, the value must be at least as large as the sum of the values 
specified for the KEYLEN and BLKSIZE operands. If the BUFL operand is 
omitted,the system constructs buffers with a length equal to the sum of the values 
specified in the KEYLEN and BLKSIZE operands. 
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The BUFL operand must be specified when an existing BDAM data set is being 
processed and dynamic buffering is requested. Its value must be at least as large as the 
value specified for the BLKSIZE operand when the READ or WRITE macro 
instruction specifies a key address, or the value specified in the BUFL operand must 
be at least as large as the sum of the values specified in the KEYLEN and BLKSIZE 
operands if the READ and WRITE macro instructions specify ‘S’ for the key address. 


The BUFL operand can be omitted if the buffer pool is constructed by a BUILD or 
GETPOOL macro instruction or if the problem program controls all buffering. 


Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BUFNO=absexp (maximum value is 255) 
The BUFNO operand specifies the number of buffers to be constructed by a BUILD 
macro instruction, or it specifies the number of buffers and/or segment work areas to 
be acquired by the system. 


If the buffer pool is constructed by a BUILD macro instruction or if buffers are 
acquired automatically when BSAM is used to create a BDAM data set, the number of 
buffers must be specified in the BUFNO operand. 


If dynamic buffering is requested when an existing BDAM data set is being processed, 
the BUFNO operand is optional; if omitted, the system acquires two buffers. 


If variable-length spanned records are being processed and dynamic buffering is 
requested, the system also acquires a segment work area for each buffer. If dynamic 
buffering is not requested, the system acquires the number of segment work areas 
specified in the BUFNO operand. If the BUFNO operand is omitted when 
variable-length spanned records are being processed and dynamic buffering is not 
requested, the system acquires two segment work areas. 


If the buffer pool is constructed by a GETPOOL macro instruction or if the problem 
program controls all buffering, the BUFNO operand can be omitted, unless it is 
required to acquire additional segment work areas for variable-length spanned records. 


Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


DDNAME=symbol 
The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 


Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 


DSORG={DA | DAU} 
The DSORG operand specifies the data set organization and if the data set contains 
any location-dependent information that would make it unmovable. For example, if 
actual device addresses are used to process a BDAM data set, the data set may be 
unmovable. The following describes the characters that can be specified: 


DA 
Specifies a direct organization data set. 
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DAU 
Specifies a direct organization data set that contains location-dependent 
information. 


When a BDAM data set is created, the basic sequential access method (BSAM) is 
used. The DSORG operand in the DCB macro instruction must be coded as 
DSORG=PS or PSU when the data set is created, and the DCB subparameter in the 
corresponding DD statement must be coded as DSORG=DA or DAU. This creates a 
data set with a data set label identifying it as a BDAM data set. 


Source: The DSORG operand must be specified in the DCB macro instruction. See 
the above comment about creating a BDAM data set. 


EXLST=relexp 
The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand must be specified if the problem program processes user labels during 
the Open or Close routine, if the data control block exit routine is used for additional 
processing, or if the DCB ABEND exit is used for ABEND condition analysis. 


Refer to Appendix D of this publication for the format and requirements of exit list 
processing. For additional information about exit list processing, refer to OS/VS 
Data Management Services Guide. 


Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program before the exit is needed. 


KEYLEN=absexp (maximum value is 255) 
The KEYLEN operand specifies the length, in bytes, of all keys used in the data set. 
When keys are used, a key is associated with each data block in the data set. If the key 
length is not supplied by any source, no input or output requests that require a key can 
be specified in a READ or WRITE macro instruction. 


Source: The KEYLEN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before the 
completion of the data control block exit routine, or by an existing data set label. If 
KEYLEN=0 is specified in the DCB macro instruction, a special indicator is set in 
RECFM so that KEYLEN cannot be supplied from the DCB subparameter of a DD 
statement or data set label of an existing data set. KEYLEN=0 can be coded only in 
the DCB macro instruction and will be ignored if specified in the DD statement. 


LIMCT=absexp 
The LIMCT operand specifies the number of blocks or eens to be searched when the 
extended search option (OPTCD=E) is requested. 


When the extended search option is requested and relative block addressing is used, 
the records must be fixed-length record format. The system converts the number of 
blocks specified in the LIMCT operand into the number of tracks required to contain 
the blocks, then proceeds in the manner described below for relative track addressing. 


When the extended search option is requested and relative track addressing is used (or 
the number of blocks has been converted to the number of tracks), the system 
searches for the block specified in a READ or WRITE macro instruction (type DK), 
or it searches for available space in which to add a block (WRITE macro instruction, 
type DA). The search is as follows: 


e The search begins at the track specified by the block address operand of a READ 
or WRITE macro instruction. 


e The search continues until the search is satisfied, the number of tracks specified in 
the LIMCT operand have been searched, or the entire data set has been searched. 
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If the search has not been satisfied when the last track of the data set is reached, 
the system continues the search by starting at the first track of the data set if the 
EOF marker is on the last track that was allocated to the data set. (This operation 
allows the number specified in the LIMCT operand to exceed the size of the data 
set, causing the entire data set to be searched.) You can insure that the EOF 
marker is on the last allocated track by determining the size of the data set and 
allocating space in blocks, or by allocating space in tracks and including the RLSE 
parameter on the SPACE operand of the DD statement (RLSE specifies that all 
unused tracks be returned to the system). 


The problem program can change the DCBLIMCT field in the data control block at 
any time, but if the extended search option is used, the DCBLIMCT field must not be 
zero when a READ or WRITE macro instruction is issued. 


If the extended search option is not requested, the system ignores the LIMCT 
operand, and the search for a data block is limited to a single track. 


Source: The LIMCT operand can be supplied in the DCB macro instruction, the DCB 
subparameter of a DD statement, or by the problem program before the count is 
required by a READ or WRITE macro instruction. 


MACRF= {(R{K[E] | UEXI[S][C])} 
{(WIATK][T] | KUT] | 3[C])3 


{(REK(T) | BEXILSI[C],WiAK][L] | KO | 3[C])} 
The MACREF operand specifies the type of macro instructions (READ, WRITE, 
CHECK, and WAIT) used when the data set is processed. The MACRF operand also 
specifies the type of search argument and BDAM functions used with the data set. 
When BSAM is used to create a BDAM data set, the BSAM operand MACRF=WL is 
specified. This special operand invokes the BSAM routine that can create a BDAM 
data set. The following describes the characters that can be specified for BDAM: 


A 
Specifies that data blocks are to be added to the data set. 


C 
Specifies that CHECK macro instructions are used to test for completion of read 
and write operations. If C is not specified, WAIT macro instructions must be used 
to test for completion of read and write operations. 


Specifies that the search argument is to be the block identification portion of the 
data block. If relative addressing is used, the system converts the relative address to 
a full device address (MBBCCHHR) before the search. 


Specifies that the search argument is to be the key portion of the data block. The 
location of the key to be used as a search argument is specified in a READ or 
WRITE macro instruction. 


Specifies that READ macro instructions are used. READ macro instructions.can be 
issued when the data set is opened for INPUT, OUTPUT, or UPDAT. 


Specifies that dynamic buffering is requested by specifying ‘S’ in the area address 
operand of a READ or WRITE macro instruction. 


WwW 
Specifies that WRITE macro instructions are used. WRITE macro instructions can 
be issued only when the data set is opened for OUTPUT or UPDAT. 
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x 
Specifies that READ macro instructions request exclusive control of a data block. 
When exclusive control is requested, the data block must be released by a 
subsequent WRITE or RELEX macro instruction. 


Source: The MACRF operand must be supplied in the DCB macro instruction. 


OPTCD=[R | A][E][F][W] 
The OPTCD operand specifies the optional services that are to be used with the 
BDAM data set. These options are related to the type of addressing used, the 
extended search option, block position feedback, and write-validity checking. The 
following describes the characters that can be specified (the characters can be 
specified in any order and no commas are allowed between characters): 


A 
Specifies that actual device addresses (MBBCCHHR) are provided to the system 
when READ or WRITE macro instructions are issued. 


Specifies that the extended search option is used to locate data blocks or available 
space into which a data block can be added. When the extended search option is 
specified, the number of blocks or tracks to be searched must be specified in the 
LIMCT operand. The extended search option is ignored if actual addressing 
(OPTCD=A) is also specified. The extended search option requires that the data 
set have keys and that the search be made by key (by specifying DK in the READ 
or WRITE macro or DA in the WRITE macro). 


Specifies that block position feedback requested by a READ or WRITE macro 
instruction is to be in the same form that was originally presented to the system in 
the READ or WRITE macro instruction. If the F operand is omitted, the system 
provides feedback, when requested, in the form of an 8-byte actual device address. 
(Feedback is always provided if exclusive control is requested.) 


R 
Specifies that relative block addresses (in the form of a 3-byte binary number) are 
provided to the system when a READ or WRITE macro instruction is issued. 


WwW 
Specifies that the system performs a validity check for each record written. 


Note: Relative track addressing can only be specified by omitting both A and R from 
the OPTCD operand. If you want to specify relative track addressing after your data 
set has been accessed using another addressing scheme (OPTCD=A or R), you should 
either specify a valid OPTCD operand (E, F, or W) in the DCB macro or DD card 
when you reopen your data set, or zero out the OPICD=A or R bits in the data 
control block exit routine. Note that the first method will prevent the open routines 
from merging any of the other OPTCD bits from the format-1 DSCB in the DCB. 
Both methods will update the OPTCD in the DSCB if the open is for OUTPUT, 
OUTIN, or UPDAT. 


Source: The OPTCD operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before an OPEN 
macro instruction is issued to open the data set. 
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RECFM={U | V[S | BS] | F[T]} 
The RECFM operand specifies the format and characteristics of the records in the 
data set. The following describes the characters that can be coded (if the optional 
characters are coded, they must be coded in the order shown above): 


B 
Specifies that the data set contains blocked records. The record format 
RECFM=VBS is the only combination in which B can be specified. RECFM=VBS 
does not cause the system to process spanned records; the problem program must 
block and segment the records. RECFM=VBS is treated as a variable-length record 
by BDAM. 


Specifies that the data set contains fixed-length records. 


Specifies that the data set contains variable-length spanned records when it is 
coded as RECFM=VS. When RECFM=VBS is coded, the records are treated as 
variable-length records, and the problem program must block and segment the 
records. 


Specifies that the track-overflow feature is used with the data set. The 
track-overflow feature allows a record to be partially written on one track and the 
remainder is written on the following track (if required). 


U 
Specifies that the data set contains undefined-length records. 


V 
Specifies that the data set contains variable-length records. 


Source: The RECFM operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, the problem program before completion of the 
data control block exit routine, or by the data set label of an existing data set. 


SYNAD=relexp 
The SYNAD operand specifies the address of the error analysis routine to be given 
control when an uncorrectable input/output error occurs. The contents of the 
registers when the error analysis routine is given control are described in Appendix A 
of this publication. 


The error analysis routine must not use the save area pointed to by register 13 because 
this area is used by the system. The system does not restore registers when it regains 
control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction which uses the address in register 14 to return control to 
the system. When control is returned in this manner, the system returns control to the 
problem program and proceeds as though no error had been encountered. When a 
BDAM data set is being created, a return from the error analysis routine to the system 
causes abnormal termination of the task. 


If the SYNAD operand is omitted, the task is abnormally terminated when an 
uncorrectable input/output error occurs. 


Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error routine address at 
any time. 
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DCB-——Construct a Data Control Block (BISAM) 


The data control block for the basic indexed sequential access method (BISAM) is 
constructed during assembly of the problem program. The DCB macro instruction must 
not be coded within the first 16 bytes of addressability for the control section (CSECT). 
The DSORG and MACRF operands must be coded in the DCB macro instruction, but 
the other DCB operands can be supplied from other sources. Each BISAM DCB operand 
description contains a heading, “Source.” The information under this heading describes 
the sources from which the operand can be supplied to the data control block. 


Before a DCB macro instruction for a BISAM data set is coded, the following 
characteristics of BISAM data sets should be considered: 


« BISAM cannot be used to create an indexed sequential data set. 


e BISAM performs the functions of direct retrieval of a logical record by key, direct 
update-in-place for a block of records, direct insertion of a new record in its correct 
key sequence. | 


¢ Buffering can be controlled by the problem program, or dynamic buffering can be 
specified in the DCB macro instruction and subsequently requested in a READ macro 
instruction. 


e The problem program must synchronize I/O operations by issuing a CHECK or 
WAIT macro instruction to test for completion of Read and Write operations. 


e Additional DCB operands provide the capability of reducing input/output operations 
by defining work areas to contain the highest level master index and the records being 
processed. | 


For additional information about the characteristics of BISAM processing, refer to 
OS/VS Data Management Services Guide. 


The DCB macro for BISAM is written as follows: 


[symbol | | DCB [BFALN={F | D}] 
[_BUFCB= relexp | 
[BUFL= absexp | 
[BUFNO= absexp | 
[DDNAME= symbol |! 
DSORG=IS 
[EXLST= relexp | 


MACRF= {(R[S][C)} | 
{(W{ULA] | A}[C])} 
{(R[U[S] | SI[C], W{U[A] | A}IC)} 


[MSHI= relexp | 
[MSW A= relexp | 
[NCP= absexp | 
[SMSI=absexp] | 
[SMSW = absexp | 
[SYNAD= relexp | 


1 This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 
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The following describes the DCB operands that can be supplied when the basic indexed 
sequential access method is used: 


BFALN={F | D} 
The BFALN operand specifies the boundary alignment for each buffer in the buffer 
pool when the buffer pool is acquired for use with dynamic buffering or when the 
buffer pool is constructed by a GETPOOL macro instruction. If the BFALN operand 
is omitted, the system provides doubleword alignment for each buffer. The following 
describes the characters that can be specified: 


F 
Specifies that each buffer is on a fullword boundary that is not also a doubleword 
boundary. 


D 
Specifies that each buffer is on a doubleword boundary. 


If the BUILD macro instruction is used to construct the buffer pool or the problem 
program controls all buffering, the problem program must provide an area for the 
buffers and control buffer alignment. 


Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BUFCB=relexp 
The BUFCB operand specifies the address of the buffer pool control block when the 
buffer pool is constructed by a BUILD macro instruction. | 


If dynamic buffering is requested or the buffer pool is constructed by a GETPOOL 
macro instruction, the system places the address of the buffer pool control block into 
the data control block, and the BUFCB operand must be omitted. The BUFCB 
operand must be omitted if the problem program controls all buffering. 


Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


BUFL=absexp (maximum value is 32,760) 
The BUFL operand specifies the length of each buffer to be constructed by a BUILD 
or GETPOOL macro instruction. When the data set is opened, the system computes 
the minimum length required and verifies that the length in the buffer pool control 
block is equal to or greater than the minimum required. The system then inserts the 
computed length into the BUFL field of the data control block. 


If dynamic buffering is requested, the system computes the buffer length required, and 
the BUFL operand is not required. 


If the problem program controls all buffering, the BUFL operand is not required. 
However, an ISAM data set requires additional buffer space for system use. For a 
description of the buffer length required for various ISAM operations, refer to 
OS/VS Data Management Services Guide. 


Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BUFNO=absexp (maximum value is 255) 
The BUFNO operand specifies the number of buffers requested for use with dynamic 
buffering, or it specifies the number of buffers to be constructed by a BUILD macro 
instruction. If dynamic buffering is requested but the BUFNO operand is omitted, the 
system automatically acquires two buffers for use with dynamic buffering. 
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If the GETPOOL macro instruction is used to construct the buffer pool, the BUFNO 
operand is not required. 


Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


DDNAME=symbol | 
The DDNAME operand specifies the name used to identify the job control language 
data definition statement that defines the ISAM data set to be processed. 


Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 


DSORG=IS 
The DSORG operand specifies the indexed sequential organization of the data set. IS 
is the only combination of characters that can be coded for BISAM. 


Source: The DSORG operand must be coded in the DCB macro instruction as well as 
in the DCB subparameter of a DD statement unless it is for a data set passed from a 
previous job step. In this case, DSORG may be omitted from the DD statement. 


EXLST=relexp 
The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required if the problem program uses the data control block exit 
routine for additional processing or if the DCB ABEND exit is used for ABEND 
condition analysis. 


Refer to Appendix D of this publication for the format and requirements for exit list 
processing. For additional information about exit list processing, refer to OS/VS 
Data Management Services Guide. 


Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program before the associated exit is required. 


MACRF= {(R[S][C])} 
{(W{UIA] | A}[C])} 


{(R[U[S] | S][C],W{U[A] | A}[C])} 
The MACRF operand specifies the type of macro instructions (READ, WRITE, 
CHECK, WAIT, and FREEDBUF) and type of processing (add records, dynamic 
buffering, and update records) to be used with the data set being processed. The 
operand can be coded in any of the combinations shown above; the following 
describes the characters that can be coded: 


A 
Specifies that new records are to be added to the data set. This character must be 
coded if WRITE KN macro instructions are used with the data set. 


C 
Specifies that the CHECK macro instruction is used to test I/O operations for 
completion. If C is not coded, WAIT macro instructions must be used. 


R | 
Specifies that READ macro instructions are used. 


S 
Specifies that dynamic buffering is requested in READ macro instructions. S should 
not be specified if the problem program provides the buffer pool. 
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U 
Specifies that records in the data set will be updated in place. If U is coded in 
combination with R, it must also be coded in combination with W. For example, 
MACRF=(RU,WU). 


Ww 
Specifies that WRITE macro instructions are used. 


Source: The MACRF operand must be coded in the DCB macro instruction. 


MSHI=relexp 
The MSHI operand specifies the address of the storage area used to contain the 
highest level master index for the data set. The system uses this area to reduce the 
search time required to find a given record in the data set. The MSHI operand is 
coded only when the SMSI operand is coded. 


Source: The MSHI operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


MSWA-=relexp 
The MSWA operand specifies the address of the storage work area to be used by the 
system when new records are being added to the data set. This operand is optional, 
but the system acquires a minimum-size work area if the operand is omitted. The 
MSWA operand is coded only when the SMSW operand is coded. 


Processing efficiency can be increased if more than a minimum-size work area is 
provided. For more detailed information about work area size, refer to OS/VS Data 
Management Services Guide. 


Note: QISAM uses the DCBMSWA, DCBSMSI, and DCBSMSW fields in the data 
control block as a work area; these fields contain meaningful information only when 
the data set is opened for BISAM. 


Source: The MSWA operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


NCP=absexp (maximum value is 99) 
The NCP operand specifies the maximum number of READ/WRITE macro 
instructions that are issued before the first CHECK (or WAIT) macro instruction is 
issued to test for completion of the I/O operation. The maximum number that can be 

| specified may be less than 99 depending on the amount of virtual storage available in 
the region or partition. If the NCP operand is omitted, one is assumed. If dynamic 
buffering is used, the value specified for the NCP operand must not exceed the 
number of buffers specified in the BUFNO operand. 


Source: The NCP operand can be supplied in the DCB macro instruction, in the DCB 
| subparameter of a DD statement, or by the problem program before completion of the 
data control block open exit routine. 


SMSlI=absexp (maximum value is 65,535) 
The SMSI operand specifies the length, in bytes, required to contain the highest level 
master index for the data set being processed. The size required can be determined 
from the DCBNCRHI field of the data control block. When an ISAM data set is 
created (with QISAM), the size of the highest level index is inserted into the 
DCBNCRHI field. If the value specified in the SMSI operand is less than the value in 
the DCBNCRHI field, the task is abnormally terminated. 


Note: OISAM uses the DCBMSWA, DCBSMSI, and DCBSMSW fields as a work 
area; these fields contain meaningful information only when the data set is opened for 
BISAM. 
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Source: The SMSI operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


SMSW =absexp (maximum value is 65,535) 
The SMSW operand specifies the length, in bytes, of a work area that is used by 
BISAM. This operand is optional, but the system acquires a minimum-size work area 
if the operand is omitted. The SMSW operand is coded only when the MSWA 
operand is also coded. If the SMSW operand is coded but the size specified is less 
than the minimum required, the task is abnormally terminated. OS/VS Data 
Management Services Guide describes the methods of calculating the size of the 
work area. 


If unblocked records are used, the work area must be large enough to contain all the 
count fields (eight bytes each), key fields, and data fields contained on one 
direct-access device track. 


If blocked records are used, the work area must be large enough to contain all the 
count fields (eight bytes each) and data fields contained on one direct-access device 
track plus additional space for one logical record (LRECL value). 


Note: QISAM uses the DCBMSWA, DCBSMSI, and DCBSMSW fields in the data 
control block as a work area; these fields contain meaningful information only when 
the data set is opened for BISAM. 


Source: The SMSW operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


SYNAD=relexp 
The SYNAD operand specifies the address of the error anlaysis routine given control 
when an uncorrectable input/output error occurs. The contents of the registers when 
the error analysis routine is given control are described in Appendix A of this 
publication. 


The error anlaysis routine must not use the save area pointed to by register 13 because 
this area is used by the system. The system does not restore registers when it regains 
control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction which uses the address in register 14 to return control to 
the system. When control is returned in this manner, the system returns control to the 
problem program and proceeds as though no error had been encountered. If the error 
analysis routine continues processing, the results are unpredictable. 


If the SYNAD operand is omitted, the task is abnormally terminated when an 
uncorrectable input/output error occurs. 


Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error analysis routine 
address at any time. 
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DCB—Construct a Data Control Block (BPAM) 


The data control block for the basic partitioned access method (BPAM) is constructed 
during assembly of the problem program. The DCB macro instruction can be coded at 
any point in a control section (CSECT). The DSORG and MACRF operands must be 
specified in the DCB macro instruction, but the other DCB operands can be supplied 
from other sources. Each of the BPAM DCB operand descriptions contains a heading, 
“Source.” The information under this heading describes the sources which can supply the 
operand to the data control block. 


Before a DCB macro instruction for a BPAM data set is coded, the following 
characteristics of partitioned data sets should be considered: 


« The entire partitioned data set must reside on one direct-access volume, but several 
such data sets, on the same or different volumes, can be concatenated for input. 


e When a partitioned data set is being created, the first (or only) DD statement for the 
data set must contain a SPACE parameter defining the size of the entire data set and 
its directory. From this information, the system allocates space for the data set and 
pre-formats the data set directory. As subsequent data set members are added, they 
are added in the space originally allocated. 


e A single member of a partitioned data set can be added or retrieved using BSAM or 
QSAM without using the BLDL, FIND, or STOW macro instructions. In this case, the 
data set member is being processed as a sequential data set (DSORG=PS). Processing 
a member in this manner does not provide the full capability of the basic partitioned 
access method. For more information about processing a member using BSAM or 
QSAM, refer to OS/VS Data Management Services Guide. 


e A single member or multiple members can be added, retrieved, or updated using 
BPAM (many of the routines used by BPAM are actually BSAM routines). 


e« Buffers fora BPAM data set can be acquired automatically, but buffer control must 
be provided by the problem program. The problem program must issue a READ 
macro instruction that provides a buffer address to fill an input buffer, and it must 
place the data in an output buffer before issuing a WRITE macro instruction to write 
a data block. 


e« Although a BPAM data set can contain blocked records, the problem program must 
perform all blocking and deblocking of records. BPAM provides only the capability to 
read or write a data block, but the data block can contain multiple logical records 
assembled by the problem program. 


¢ The STOW macro instruction can be used to add, delete, change, or replace a member 
name or alias in the directory. 


e Multiple members of the data set can be processed by building a list of member 
locations (with a BLDL macro instruction) and using the FIND macro instruction (in 
conjunction with the list) to locate the beginning of each member. 


e The problem program must synchronize I/O operations by issuing a CHECK macro 
instruction for each READ or WRITE macro instruction issued. 


These characteristics of partitioned data sets and the basic partitioned access method are 
described in more detail in OS/VS Data Management Services Guide. 
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The DCB macro for BPAM is written as follows: 


a ee a et tN A A were herent A A a epee ES 


[BFALN={F | D}] 
[BLKSIZE= absexp | 
[BUFCB= relexp | 
[BUFL= absexp | 
[BUFNO = absexp | 
[DDNAME= symbol |! 
DSORG={PO | POU} 
[EODAD= relexp | 
[EXLST= relexp | 
[KEYLEN= absexp | 
[LRECL= absexp | 
MACRF={(R | W|R,W)}! 
[INCP= absexp | 
[OPTCD={C | W[C]}] 


[RECFM={U[T][A | M]} 
{V([B[T] | T][A | MJ} 
{F(B[T] | TILA | MJ) 
[SYNAD= relexp | 


[ symbol | | DCB 





1 This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 


The following describes the DCB operands that can be specified when a BPAM data set 
is being created or processed: 


BFALN={F | D} 
The BFALN operand specifies the boundary alignment for each buffer in the buffer 
pool when the buffer pool is constructed automatically or by a GETPOOL macro 
instruction. If the BFALN operand is omitted, the system provides doubleword 
alignment for each buffer. The following describes the characters that can be specified 
in the BFALN operand: 
F 
Specifies that each buffer is aligned on a fullword boundary that is not also a 
doubleword boundary. 


D 
Specifies that each buffer is aligned on a doubleword boundary. 


If the BUILD macro instruction is used to construct the buffer pool or if the problem 
program controls all buffering, the problem program must provide an area for the 
buffers and control buffer alignment. 


Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BLKSIZE=absexp (maximum value is 32,760) 
The BLKSIZE operand specifies the length, in bytes, of each data block for 
fixed-length records, or it specifies the maximum length, in bytes, for variable-length 
or undefined-length records. If keys are used, the length of the key is not included in 
the value specified for the BLKSIZE operand. 


The actual block size that can be specified depends on the record format and the type 
of direct-access device being used. If the track-overflow feature is used, the block size 
can be up to the maximum. If the track-overflow feature is not used, the maximum 
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block size is determined by the track capacity of a single track on the direct-access 
device being used. Device capacity for direct-access devices is described in Appendix 
C of this publication. For additional information about device capacity and space 
allocation, refer to OS/VS Data Management Services Guide. 


For variable-length records, the value specified in the BLKSIZE operand must include 
the maximum logical record length (up to 32,756 bytes) plus four bytes for the block 
descriptor word (BDW). 


For undefined-length records, the value specified for the BLKSIZE operand can be 
altered by the problem program when the actual length becomes known to the 
problem program. The value can be inserted into the DCBBLKSI field of the data 
control block or specified in the length operand of a READ/WRITE macro 
instruction. 


Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 


BUFCB=relexp 
The BUFCB operand specifies the address of the buffer pool control block when the 
buffer pool is constructed by a BUILD macro instruction. 


If the buffer pool is constructed automatically or by a GETPOOL macro instruction, 
the system places the address of the buffer pool control block into the data control 
block and the BUFCB operand can be omitted. Also, if the problem program controls 
all buffering, the BUFCB operand should be omitted. 


Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


BUFL=absexp (maximum value is 32,760) 
| The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool 
when the buffer pool is acquired automatically. If the BUFL operand is omitted and 
the buffer pool is acquired automatically, the system acquires buffers with a length 
that is equal to the sum of the values specified in the KEYLEN and BLKSIZE 
operands. If the problem program requires longer buffers, the BUFL operand should 
be specified. 


If the problem program controls all buffering, the BUFL operand is not required. 


Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BUFNO=absexp (maximum value is 255) 
The BUFNO operand specifies the number of buffers to be constructed by a BUILD 
macro instruction, or it specifies the number of buffers to be acquired automatically 
by the system. 


If the problem program controls all buffering or if the buffer pool is constructed by a 
GETPOOL macro instruction, the BUFNO operand should be omitted. 


Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


DDNAME=symbol 
The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 
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Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 


DSORG={PO | POU} 
The DSORG operand specifies the data set organization and if the data set contains 
any location-dependent information that would make it unmovable. The following 
describes the characters that can be specified: 


PO 
Specifies a partitioned data set organization. 


POU 
Specifies a partitioned data set organization and that the data set contains 
location-dependent information. 


Note: If BSAM or QSAM is used to add or retrieve a single member of a partitioned 
data set, a sequential access method is being used, and the DSORG operand is 
specified as PS or PSU. The name of the member being processed in this manner is 
supplied in a DD statement. 


Source: The DSORG operand must be specified in the DCB macro instruction. 


EODAD=relexp 
The EODAD operand specifies the address of the routine given control when the end 
of the input data set is reached. Control is given to this routine when an input request 
is made (READ macro instruction) and there are no additional input records to 
retrieve. The routine is entered when a CHECK macro instruction is issued and the 
end of the data set is reached. If the end of the data set is reached and no EODAD 
address has been supplied, the task is abnormally terminated. For additional 
information on the EODAD routine, see OS/VS Data Management Services Guide. 


Source: The EODAD operand can be supplied in the DCB macro instruction or by the 
problem program before the end of the data set is reached. 


EXLST=relexp 
The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required if the problem program uses the data control block exit 
routine for additional processing or if the DCB ABEND exit is used for ABEND 
condition analysis. 


Refer to Appendix D of this publication for the format and requirements of the exit 
list processing. For additional information about exit list processing, refer to OS/VS 
Data Management Services Guide. 


Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program before the OPEN macro instruction is issued to open the data set. 


KEYLEN=absexp (maximum value is 255) 
The KEYLEN operand specifies the length, in bytes, of the key associated with each 
data block in the direct-access device data set. If the key length is not supplied from 
any source by the end of the data control block exit routine, a key length of zero (no 
keys) is assumed. 


Source: The KEYLEN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before the 
completion of the data control block exit routine, or by the data set label of an 
existing data set. If KEYLEN=0 is specified in the DCB macro instruction, a special 
indicator is set in RECFM so that KEYLEN cannot be supplied from the DCB 
subparameter of a DD statement or data set label of an existing data set. KEYLEN=0 
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can be coded only in the DCB macro instruction and will be ignored if specified in the 
DD statement. 


LRECL=absexp (maximum value is 32,760) 


The LRECL operand specifies the length, in bytes, of each fixed-length logical record 
in the data set; It is required only for fixed-length records. The value specified in the 
LRECL operand cannot exceed the value specified in the BLKSIZE operand. 


If the records are unblocked, the value specified in the LRECL operand must equal 
the value specified in the BLKSIZE operand. If the records are blocked, the value 
specified in the LRECL operand must be evenly divisible into the value specified in 
the BLKSIZE operand. 


Source: The LRECL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 


MACRF={(R | W|R,W)} 


The MACRF operand specifies the type of macro instructions (READ, WRITE, and 
NOTE/POINT) that are used to process the data set. The following describes the 
characters that can be specified: 


R 
Specifies that READ macro instructions are used. This operand automatically 
provides the capability to use both the NOTE and POINT macro instructions with 
the data set. 


WwW 
Specifies that WRITE macro instructions are used. This operand automatically 
provides the capability to use both the NOTE and POINT macro instructions with 
the data set. 


All BPAM READ and WRITE macro instructions issued must be tested for 
completion using a CHECK macro instruction. The MACRF operand does not require 
any coding to specify that a CHECK macro instruction will be used. 


Source: The MACRF operand must be specified in the DCB macro instruction. 


NCP=absexp (maximum value is 99) 


The NCP operand specifies the maximum number of READ and WRITE macro 
instructions that will be issued before the first CHECK macro instruction is issued. 
The maximum number may be less than 99 depending on the amount of virtual 
storage available in the region or partition. If chained scheduling is specified, the value 
of NCP determines the maximum number of channel program segments that can be 
chained and must be specified as more than one. If the NCP operand is omitted, one is 
assumed. 


Source: The NCP operand can be supplied in the DCB macro instruction, in the DCB 
subparameter of a DD statement, or by the problem program before completion of the 
data control block open exit routine. 
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OPTCD={C | W[C]} 
The OPTCD operand specifies the optional services performed by the system. The 
following describes the characters that can be specified; they can be specified in any 
| order and no commas are allowed between characters: 


C 
| Specifies that chained scheduling is used. OS/VS1 supports chained scheduling in 
nonpageable storage only. If chained scheduling is requested in pageable storage, 
the request is ignored and normal scheduling is substituted. 


| For OS/VS2, chained scheduling is supported for pageable and nonpageable 
storage. 


Ww 
Specifies that the system performs a validity check for each record written. 


Source: The OPTCD operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before an OPEN 
macro instruction is issued to open the data set. However, all optional services must be 
requested from the same source. 


RECFM= {U[T][A | M]} 
{V[B[T] | T][A | MJ} 


{F[B[T] | T][A | M}} 
The RECFM operand specifies the record format and characteristics of the data set 
being created or processed. All the record formats shown above can be specified, but 
in those formats that show blocked records, the problem program must perform the 
blocking and deblocking of logical records; BPAM recognizes only data blocks. The 
following describes the characters that can be specified: 


A 
Specifies that the records in the data set contain American National Standards 
Institute (ANSI) control characters. Refer to Appendix E for a description of 
control characters. 


B 
Specifies that the data set contains blocked records. 


F 
Specifies that the data set contains fixed-length records. 


M 
Specifies that the records in the data set contain machine code control characters. 
Refer to Appendix E for a description of control characters. 


T 
Specifies that the track-overflow feature is used with the data set. The 
track-overflow feature allows a record to be written partially on one track of a 
direct-access device and the remainder of the record written on the following track 
(if required). Chained scheduling (OQPTCD=C) cannot be used if the 
track-overflow feature is used. 


U 
Specifies that the data set contains undefined-length records. 


Vv 
Specifies that the data set contains variable-length records. 


Source: The RECFM operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 
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SYNAD=relexp 
The SYNAD operand specifies the address of the error analysis (SYNAD) routine to 
be given control when an uncorrectable input/output error occurs. The contents of 
the registers when the error analysis routine is given control are described in 
Appendix A. 


The error analysis routine must not use the save area pointed to by register 13, 
because this area is used by the system. The system does not restore registers when it 
regains control from the error analysis routine. The error analysis routine can return 
control to the system by issuing a RETURN macro instruction. If control is returned 
to the system, the system returns control to the problem program and proceeds as 
though no error had been encountered. 


If the SYNAD operand is omitted, the task is abnormally terminated when an 
uncorrectable input/output error occurs. 


Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error routine address at 
any time. 
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DCB—Construct a Data Control Block (BSAM) 


The data control block for the basic sequential access method (BSAM) is constructed 
during assembly of the problem program. The DSORG and MACRF operands must be 
coded in the DCB macro instruction, but the other DCB operands can be supplied, to the 
data control block, from other sources. Each DCB operand description contains a 
heading, “‘Source.’”’ The information under this heading describes the sources from which 
an operand can be supplied. 


Before a DCB macro instruction for creating or processing a BSAM data set is coded, the 
following characteristics of BSAM data sets should be considered: 


e« Although several record formats with blocked records can be specified for BSAM, the 
problem program must perform all blocking and deblocking of records. BsSAM 
provides only the capability to read or write a data block, but the block can contain 
one or more logical records assembled by the problem program. 


e Buffers for a BSAM data set can be acquired automatically, but buffer control must 
be provided by the problem program. The problem program must issue a READ 
macro instruction that provides a buffer address to fill an input buffer, and it must 
place the data in an output buffer before issuing the WRITE macro instruction to 
write a data block. 


¢ The problem program must synchronize I/O operations by issuing a CHECK macro 
instruction for each READ and WRITE macro instruction issued. 


e BSAM provides capability for nonsequential processing by using the NOTE and 
POINT macro instructions. 


e Keys for direct-access device records can be read or written using BSAM. 


e Specifying the DEVD operand in the DCB macro instruction can make the program 
device dependent. 


These characteristics of basic sequential access method data sets are described in more 
detail in OS/VS Data Management Services Guide. 


For information on additional operands for the DCB macro for the 1275 or 1419, see 
OS Data Management Services and Macro Instructions for IBM 1419/1275, 


For information on additional operands for the DCB macro for the 3886, see OS/VS 
IBM 3886 Optical Character Reader Model 1 Reference. 
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The DCB macro for BSAM is written as follows: 


[symbol | | DCB 


[BFALN={F | D}] 
[BFTEK=R] 
[BLKSIZE= absexp | 
[BUFCB= relexp | 
[BUFL= absexp ] 
[BUFNO= absexp | 
[BUFOFF={ absexp | L}] 
[DDNAME= symbol }! 


[DEVD= {DA 
[ KEYLEN= absexp ]} 


{TA 7 
[,DEN={0| 1/2/3143] 
[ TRTCH={C|E]|ET|T}]} 


{PT 
[CODE={A|B|C|F|I|N|T}]} 


{PR 
LPRTSP={0|1|2|33]3 


iPC | 
[LMODE=[C | E][R]] 
[,STACK={1 | 23] | 
[|,FUNC={I| P| PW[XT] | R| RP[D] | RW[T] | 
RWP([XT][D] | W[T]}]} 






{RD 
[, MODE=[C | E][0| RJ] 
[| STACK={1 | 23] 
[,.FUNC={I|P | PW[XT]|R | RP[D]| RW[T] | 
RWP[XT][D] | W[T]}]3] 


DSORG={PS | PSU} 
[EODAD= relexp | 
[EXLST= relexp | 
[KEYLEN=absexp]_ . 
[LRECL={ absexp | X}] 


MACRF= {(R[C| P])} 
i(w[C| P| L})} 
{(R[C],W[C]) $1 

[INCP= absexp | 


1 This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 


Continued on next page. 
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[OPTCD= {B} 
iT} 
tU[C]} 
iC[T][B]} 
{H[Z][B]} 
tWICI[T][B}3 


{Z[C][TIB}} 
— {QLCIBIT | Z1}) 
[RECFM={U[TIIA | M]} 
{V[B|S|T|BS|BT][A|M]} 
{D[B][A]} 
{F[B|S|T|BS|BT][A | M]}] 
[SYNAD= relexp ] 





The following describes the operands that can be specified in the DCB macro instruction 
for a BSAM data set: 


BFALN={F | D} 
The BFALN operand specifies the boundary alignment for each buffer in the buffer 
pool when the buffer pool is constructed automatically or by a GETPOOL macro 
instruction. If the BFALN operand is omitted, the system provides doubleword 
alignment for each buffer. 


If the data set being created or processed contains ASCII tape records with a block 
prefix, the block prefix is entered at the beginning of the buffer, and data alignment 
depends on the length of the block prefix. For a description of how to specify the 


block prefix length, refer to the DCB BUFOFF operand. 

The following describes the characters that can be specified: 

F | 
Specifies that each buffer is on a fullword boundary that is not also a doubleword 
boundary. 


D 
Specifies that each buffer is on a doubleword boundary. 


If the BUILD macro instruction is used to construct the buffer pool or if the problem 
program controls all buffering, the problem program must provide an area for the 
buffers and control buffer alignment. 


Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFALN and BFTEK operands are 
specified, they must be supplied by the same source. 


BFTEK=R 
The BFTEK=R operand specifies that BSAM is used to read unblocked 
variable-length spanned records with keys from a BDAM data set. Each read 
operation reads one segment of the record and places it in the area designated in the 
READ macro instruction. The first segment enters at the beginning of the area, but all 
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subsequent segments are offset by the length of the key (only the first segment has a 
key). The problem program must provide an area in which to assemble a record, 
identify each segment, and assemble the segments into a complete record. 


Source: The BFTEK operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFTEK and BFALN operands are 
specified, they must be supplied from the same source. 


BLKSIZE=absexp (maximum value is 32,760) 
The BLKSIZE operand specifies the maximum block length in bytes. For fixed-length, 
unblocked records, this operand specifies the record length. The BLKSIZE operand 
includes only the data block length; if keys are used, the length of the key is not 
included in the value specified for the BLKSIZE operand. 


The actual value that can be specified in the BLKSIZE operand depends on the device 
type and the record format being used. Device capacity is shown in Appendix C of 
this publication. For additional information about device capacity, refer to OS/VS 
Data Management Services Guide. For direct-access devices when the 
track-overflow feature is used or variable-length spanned records are being processed, 
the value specified in the BLKSIZE operand can be up to the maximum value. For 
other record formats used with direct-access devices, the value specified for BLKSIZE 
cannot exceed the capacity of a single track. 


If fixed-length records are used for a SYSOUT data set, the value specified in the 
BLKSIZE operand must be an integral multiple of the value specified for the logical 
record length (LRECL); otherwise the system will adjust the block size downward to 
the nearest multiple. 


If variable-length records are used, the value specified in the BLKSIZE operand must 
include the maximum logical record length (up to 32,756 bytes) plus the four bytes 
required for the block descriptor word (BDW). For format-D variable-length records 
(ASCII data sets), the minimum value for BLKSIZE is 18 bytes and the maximum 
value is 2,048 bytes. 


If ASCII tape records with a block prefix are processed, the value specified in the 
BLKSIZE operand must also include the length of the block prefix. 


If BSAM is used to read variable-length spanned records from a BDAM data set, the 
value specified for the BLKSIZE operand must be as large as the longest possible 
record segment in the BDAM data set, including four bytes for the segment descriptor 
word (SDW) and four bytes for the block descriptor word (BDW). 


If undefined-length records are used, the value specified for the BLKSIZE operand 
can be altered by the problem program when the actual length becomes known to the 
problem program. The value can be inserted directly into the DCBBLKSI field of the 
data control block or specified in the /Jength operand of a READ/WRITE macro 
instruction. 


Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 


BUFCB=relexp 
The BUFCB operand specifies the address of the buffer pool control block in a buffer 
pool constructed by a BUILD macro instruction. 


If the buffer pool is constructed automatically or by a GETPOOL macro instruction, 
the system places the address of the buffer pool control block into the data control 
block, and the BUFCB operand should be omitted. If the problem program controls all 
buffering, the BUFCB operand is not required. 
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Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


BUFL=absexp (maximum value is 32,760) 
The BUFL operand specifies the length, in bytes, for each buffer in the buffer pool 
when the buffer pool is acquired automatically. The system acquires buffers with a 
length equal to the sum of the values specified in the KEYLEN and BLKSIZE 
operands if the BUFL operand is omitted; if the problem program requires larger 
buffers, the BUFL operand must be specified. If the BUFL operand is specified, it 
must be at least as large as the value specified in the BLKSIZE operand. If the data set 
is for card image mode, the BUFL operand should be specified as 160. The description 
of the DEVD operand contains a description of card image mode. 


If the data set contains ASCII tape records with a block prefix, the value specified in 
the BUFL operand must include the block length plus the length of the block prefix. 


If the problem program controls all buffering or if the buffer pool is constructed by a 
GETPOOL or BUILD macro instruction, the BUFL operand is not required. 


Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BUFNO=absexp (maximum value is 255) 
The BUFNO operand specifies the number of buffers constructed by a BUILD macro 
instruction or the number of buffers to be acquired automatically by the system. 


If the problem program controls all buffering or if the buffer pool is constructed by a 
GETPOOL macro instruction, the BUFNO operand should be omitted. 


Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BUFOFF=} absexp | L} 
The BUFOFF operand specifies the length, in bytes, of the block prefix used with an 
ASCII tape data set. When BSAM is used to read an ASCII tape data set, the problem 
program must use the block prefix length to determine the location of the data in the 
buffer. When BSAM is used to write an output ASCII tape data set, the problem 
program must insert the block prefix into the buffer followed by the data (BSAM 
considers the block prefix as data). The block prefix and data can consist of any 
characters that can be translated into ASCII code; any character that cannot be 
translated is replaced with a substitute character. For format-D records, the RDW 
must be binary; if RECFM=D and BUFOFF=L, then the RDW and BDW must be 
binary. On output, the control program translates the BDW and RDW to zoned 
decimal and on input, the control program converts them to binary. The following can 
be specified in the BUFOFF operand: 


absexp 
Specifies the length, in bytes, of the block prefix. This value can be from 0 to 99 
for an input data set. The value must be 0 for writing an output data set with 
fixed-length or undefined-length records (BSAM considers the block prefix part of 
the data record). 


Specifies that the block prefix is 4 bytes long and contains the block length. 
BUFOFF=L is used when format-D records (ASCII) are processed. When 
BUFOFF=L is specified, the BSAM problem program can process the data records 
(using READ and WRITE macro instructions) in the same manner as if the data 
were in format-V variable-length records. For further information on this operand, 
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see ‘“‘Variable-Length Records—Format D” in OS/VS Data Management 
Services Guide. 


If the BUFOFF operand is omitted for an input data set with format-D records, the 
system inserts the record length into the DCBLRECL field of the data control block; 
the problem program must obtain the length from this field to process the record. 


If the BUFOFF operand is omitted from an output data set with format-D records, the 
problem program must insert the actual record length into the DCBBLKSI field of the 
data control block or specify the record length in the length operand of a WRITE 
macro instruction. 


Source: The BUFOFF operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before an OPEN 
macro instruction is issued to open the data set. BUFOFF=absexp can also be 
supplied by the label of an existing data set; BUFOFF=L cannot be supplied by the 
label of an existing data set. 


DDNAME=symbol 
The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 


Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 


DEVD={DA | TA|PT|PR|PC|RD}[, options] 
The DEVD operand specifies the device type on which the data set can or does reside. 
The device types above are shown with the optional operand(s) that can be coded 
when a particular device is used. The devices are listed in order of 
device-independence. For example, if DEVD=DA is coded in a DCB macro 
instruction (or the DEVD operand is omitted, which causes a default to DA), the data 
control block constructed during assembly could later be used for any of the other 
devices, but if DEVD=RD is coded, the data control block can be used only with a 
card reader or card reader punch. Unless you are certain that device interchangeability 
is not required, you should either code DEVD=DA or omit the operand and allow it to 
default to DA. 


If system input is directed to an intermediate storage device, the DEVD operand is 
omitted, and the job control language for the problem program designates the system 
input device to be used. Likewise, if system output is directed to an intermediate 
storage device, the DEVD operand is omitted, and the job control language for the 
problem program designates the system output device to be used. 


If DEVD=PT is coded, the DCB macro should not be coded within the first 8 bytes 
of addressability for the control section (CSECT). If DEVD=PR, PC, or RD is 
coded, the DCB macro should not be coded within the first 16 bytes of addressability 
for the control section. 


The DEVD operand is discussed below according to individual device type: 


DEVD=DA 
[| KEYLEN= absexp] 
Specifies that the data control block can be used for a direct-access device (or any 
of the other device types described following DA). 


KEYLEN=absexp 
The KEYLEN operand can be specified only for data sets that reside on 
direct-access devices. Since the KEYLEN is usually coded without a DEVD 
operand (default taken), the description of the KEYLEN operand is in 
alphabetic sequence with the other operands. 
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DEVD=TA 
[DEN={0[1[2[|3| 43] 
|, TRTCH={C | E| ET | T}] 
Specifies that the data control block can be used for a magnetic tape data set (or 
any of the other device types described following TA). If TA is coded, the following 
optional operands can be coded: 


DEN={0/[1]2]3| 4} 
The DEN operand specifies the recording density in the number of bits-per-inch 
per track as shown in the following chart: 
Recording Density 


DEN 7-Track Tape 9-Track Tape 


0 200 — 
1 556 — 

2 800 800 (NRZI)! 
3 — 1600 (PE)2 

4 — 6250 (GCR)3 


1 NRZI is for non-return-to-zero inverted mode 
2 PE is for phase encoded mode 
3 GCR is for group coded recording mode 


Note: Specifying DEN=0 for a 7-track 3420 tape attached to a 3803-1 will 
result in 556 bits-per-inch recording, but corresponding messages and tape labels 
will indicate 200 bits-per-inch recording density. 


If the DEN operand is not supplied by any source, the highest applicable density 
is assumed. : 


TRTCH={C|E|ET|T} 
The TRTCH operand specifies the recording technique for 7-track tape. One of 
the above four character combinations can be coded. If the TRTCH operand is 
omitted, odd parity with no translation or conversion is assumed. The following 
describes the characters that can be specified: 


C 
Specifies that the data-conversion feature is used with odd parity and no 
translation. 


E 
Specifies even parity with no translation or conversion. 


ET 
Specifies even parity with BCDIC to EBCDIC translation required and no 
data-conversion feature. 


T 
Specifies that BCDIC to EBCDIC translation is required with odd parity and 
no data-conversion feature. 
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DEVD=PT 
[,CODE={A|B|C|F|I|N|T3] | 
Specifies that the data control block is used for a paper tape device (or any of the 
other devices following PT). If PT is coded, the following optional operand can be 
coded: 


CODE={A|B|C|F|I|N|T} 
The CODE operand specifies the code in which the data was punched. The 
system converts these codes to EBCDIC code. If the CODE operand is not 
supplied by any source, CODE=I is assumed. The following describes the 
characters that can be specified: 


A 
Specifies 8-track tape in ASCII code. 


B 
Specifies Burroughs 7-track tape. 


C 
Specifies National Cash Register 8-track tape. 


F 
Specifies Friden 8-track tape. 


I 
Specifies IBM BCD perforated tape and transmission code with 8 tracks. 


N 
Specifies that no conversion is required. 


T 
Specifies Teletype! 5-track tape. 


DEVD=PR 
[,PRTSP={0 | 1 | 2 | 33] 
Specifies that the data control block is used for an on-line printer (or any of the 
other device types following PR). If PR is coded, the following optional operand 
can be coded: 


PRTSP={0|1| 2] 3} 
The PRTSP operand specifies the line spacing on the printer. This operand is not 
valid if the RECFM operand specifies either machine (RECFM=M) or ANSI 
(RECFM=A) control characters. If the PRTSP operand is not specified from 
any source, one is assumed. The following describes the characters that can be 
specified: 


0 
Specifies that spacing is suppressed (no space). 


1 
Specifies single-spacing. 


2 ; 
Specifies double-spacing (one blank line between printed lines). 


3 
Specifies triple-spacing (two blank lines between printed lines). 


ITrademark of Teletype Corporation. 
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DEVD=PC 
|. MODE=[C | E][R]] 
[,STACK={1 | 2}] 
LFUNC={I| P| PW[XT]|R]|RP[D] | RW[T] | RWP[XT][D] | W[T]}] 
Specifies that the data control block is used for a card punch (or any of the other 
device types following PC). If PC is coded, the following optional operands can be 
specified: 


MODE=[C | E][R] 
The MODE operand specifies the mode of operation for the card punch. The 
following describes the characters that can be specified (if the MODE operand is 
omitted, E is assumed): 


C 
Specifies that the cards are to be punched in card image mode. In card image 
mode, the 12 rows in each card column are punched from two consecutive 
bytes in virtual storage. Rows 12 through 3 are punched from the low-order 6 
bits of one byte and rows 4 through 9 are punched from the low-order 6 bits 
of the following byte. 


Specifies that cards are to be punched in EBCDIC code. 


Specifies that the program runs in read-column-eliminate mode (3505 card 
reader or 3525 card punch, read feature). 


Note: If the MODE operand is specified in the DCB subparameter of a DD 
statement, either C or E must be specified if R is specified. 


STACK= {1 | 2} 
The STACK operand specifies the stacker bin into which the card is placed after 
punching is completed. If this operand is omitted, stacker number 1 is used. The 
following describes the characters that can be specified: 


1 
Specifies stacker number 1. 


Z 
Specifies stacker number 2. 


FUNC={I| P| PW[XT]|R|RP[D] | RW[T] | RWP[XT][D] | W[T]} 
The FUNC operand defines the type of 3525 card punch data sets that are used. 
If the FUNC operand is omitted from all sources, a data set opened for input 
defaults to read only, and a data set opened for output defaults to punch only. 
The following describes the characters that can be specified in the FUNC 
operand: 


D 
Specifies that the data protection option is to be used. The data protection 
option prevents punching information into card columns that already contain 
data. When the data protection option is used, an 80-byte data protection 
image (DPI) must have been previously stored in SYS1.IMAGELIB. Data 
protection applies only to the output/punch portion of a read and punch or 
read punch and print operation. 


Specifies that the data in the data set is to be punched into cards and printed 
on the cards; the first 64 characters are printed on line 1 of the card and the 
remaining 16 characters are printed on line 3. 


Macro Instruction Descriptions: DCB—BSAM 91 


P 
Specifies that the data set is for punching cards. See the description of the 
character X for associated punch and print data sets. 


Specifies that the data set is for reading cards. 


Specifies that the two-line print option is used. The two-line print option 
allows two lines of data to be printed on the card (lines 1 and 3). If T is not 
specified, the multiline print option is used; this allows printing on all 25 
possible print lines. In either case, the data printed may be the same as the 
data punched in the card, or it may be entirely different data. 


WwW 
Specifies that the data set is for printing. See the description of the character 
X for associated punch and print data sets. 


xX 
Specifies that an associated data set is opened for output for both punching 
and printing. Coding the character X is used to distinguish the 3525 printer 
output data set from the 3525 punch output data set. 


Note: If data protection is specified, the data protection image (DPI) must be 
specified in the FCB parameter of the DD statement for the data set. 


DEVD=RD 
[.MODE=[C|EI[O | R]] 
[,STACK={1 | 2H] 
| FUNC={I| P| PW[XT]|R| RP[D] | RW[T] | RWP[XT][D] | W[T]}] 
Specifies that the data control block is used with a card reader or card read punch. 
If RD is specified, the data control block cannot be used with any other device 
type. When RD is coded, the following optional operands can be specified: 


MODE=[C | EJ[O | R] 
The MODE operand specifies the mode of operation for the card reader. The 
following describes the characters that can be specified: 


Cc 
Specifies that the cards to be read are in card image mode. In card image 
mode, the 12 rows in each card column are read into two consecutive bytes of 
virtual storage. Rows 12 through 3 are read into one byte and rows 4 through 
9 are read into the following byte. 


E 
Specifies that the cards to be read contain data in EBCDIC code. 


O 
Specifies that the program runs in optical-mark-read mode (3505 card 
reader). 


R 
Specifies that the program runs in read-column-eliminate mode (3505 card 
reader or 3525 card punch, read feature). 


Note: If the MODE operand for a 3505 or 3525 is specified in the DCB 
subparameter of a DD statement, either C or E must be specified if R or O is 
specified. 
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STACK=}1 | 2} | 
The STACK operand specifies the stacker bin into which the card is placed after 
reading is completed. If this opezand is omitted, stacker number 1 is used. The 
following describes the characters that can be specified: 


1 
Specifies stacker number 1. 


2 
Specifies stacker number 2. 


FUNC={I| P| PW[XT]|R|RP[D] | RW[T] | RWP[XT][D] | W[T]} 
The FUNC operand defines the type of 3525 card punch data sets that are used. 
If the FUNC operand is omitted from all sources, a data set opened for input 
defaults to read only, and a data set opened for output defaults to punch only. 
The following describes the characters that can be specified in the FUNC 
operand: 


D 
Specifies that the data protection option is to be used. The data protection 
option prevents punching information into card columns that already contain 
data. When the data protection option is used, an 80-byte data protection 
image (DPI) must have been previously stored in SYS1.IMAGELIB. Data 
protection applies only to the output/punch portion of a read and punch or 
read punch and print operation. 


Specifies that the data in the data set is to be punched into cards and printed 
on the cards; the first 64 characters are printed on line 1 of the card and the 
remaining 16 characters are printed on line 3. 


Specifies that the data set is for punching cards. See the description of the 
character X for associated punch and print data sets. 


Specifies that the data set is for reading cards. 


Specifies that the two-line print option is used. The two-line print option 
allows two lines of data to be printed on the card (lines 1 and 3). If T is not 
specified, the multiline print option is used; this allows printing on all 25 
possible print lines. In either case, the data printed may be the same as the 
data punched in the card, or it may be entirely different data. 


WwW 
Specifies that the data set is for printing. See the description of the character 
X for associated punch and print data sets. 


xX 
Specifies that an associated data set is opened for output for both punching 
and printing. Coding the character X is used to distinguish the 3525 printer 
output data set from the 3525 punch output data set. 


Note: If data protection is specified, the data protection image (DPI) must be 
specified in the FCB subparameter of the DD statement for the data set. 


Source: The DEVD operand can be supplied only in the DCB macro instruction. 
However, the optional operands can be supplied in the DCB macro instruction, the 
DCB subparameter of a DD statement, or by the problem program before 
completion of the data control block exit routine. 
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DSORG={PS | PSU} 
The DSORG operand specifies the organization of the data set and if the data set 
contains any location-dependent information that would make it unmovable. The 
following can be specified: 


PS 
Specifies a physical sequential data set. 


PSU 
Specifies a physical sequential data set that contains location-dependent 
information that would make it unmovable. 


Source: The DSORG operand must be coded in the DCB macro instruction. 


EODAD=relexp 
The EODAD operand specifies the address of the routine given control when the end 
of an input data set is reached. If the record format is RECFM=FS or FBS, the 
end-of-data condition is sensed when a file mark is read or when more data is 
requested after reading a truncated block. The end of data routine is entered when the 
CHECK macro instruction determines that the READ macro instruction reached the 
end of the data. If the end of the data set is reached but no EODAD address has been 
supplied, the task is abnormally terminated. See OS/VS Data Management Services 
Guide for additional information on the EODAD routine. 


When the data set has been opened for UPDAT and volumes are to be switched, the 
problem program should issue a FEOV macro instruction after the EODAD routine 
has been entered. 


Source: The EODAD operand can be supplied in the DCB macro instruction or by the 
problem program before the end of the data set is reached. 


EXLST=relexp 
The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required if the problem program requires additional processing for 
user labels, user totaling, data control block exit routine, end-of-volume, block count 
exits, to define a forms control buffer (FCB) image, or to use the DCB ABEND exit 
for ABEND condition analysis. 


Refer to Appendix D of this publication for the format and requirements of exit list 
processing. For additional information about exit list processing, refer to OS/VS 
Data Management Services Guide. 


Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program any time before the exit is required by the problem program. 


KEYLEN=absexp (maximum value is 255) 
The KEYLEN operand specifies the length, in bytes, for the key associated with each 
data block in a direct-access device data set. If the key length is not supplied from any 
source before completion of the data control block exit routine, a key length of zero 
(no keys) is assumed. | 


Source: The KEYLEN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before the 
completion of the data control block exit routine, or by the data set label of an 
existing data set. If KEYLEN=0 is specified in the DCB macro instruction, a special 
indicator is set in RECFM so that KEYLEN cannot be supplied from the DCB 
subparameter of a DD statement or data set label of an existing data set. KEYLEN=0 
can be coded only in the DCB macro instruction and will be ignored if specified in the 
DD statement. 
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LRECL={ absexp |X} 

The LRECL operand specifies the length, in bytes, for fixed-length records, or it 
specifies the maximum length, in bytes, for variable-length records. LRECL=X is used 
for variable-length spanned records that exceed 32,756 bytes. Except when 
variable-length spanned records are used, the value specified for the LRECL operand 
cannot exceed the value specified for the BLKSIZE operand. 


Except when variable-length spanned records are used, the LRECL operand can be 
omitted for BSAM; the system uses the value specified in the BLKSIZE operand. If 
the LRECL value is coded, it is coded as described in the following. 


For fixed-length records that are unblocked, the value specified in the LRECL 
operand should be equal to the value specified in the BLKSIZE operand. For blocked 
fixed-length records, the value specified in the LRECL operand should be evenly 
divisible into the value specified in the BLKSIZE operand. 


For variable-length records, the value specified in LRECL must include the maximum 
data length (up to 32,752 bytes) plus 4 bytes for the RDW. 


For undefined-length records, the LRECL operand should be omitted; the actual 
length can be supplied dynamically ina READ/WRITE macro instruction. When an 
undefined-length record is read, the actual length of the record is returned by the 
system in the DCBLRECL field of the data control block. 


When BSAM is used to create a BDAM data set with variable-length spanned records, 
the LRECL value should be the maximum data length (up to 32,752) plus four bytes 
for the record descriptor word (RDW), or if the logical record length is greater than 
32,756 bytes, LRECL=X< is specified. 


Source: The LRECL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 


MACRF= {(R[C | P))} 
{(W[C| P| L)} 


{(RICLWICD} 
The MACRF operand specifies the type of macro instructions (READ, WRITE, 
CNTRL, and NOTE/POINT) that are used with the data set being created or 
processed. The BSAM MACRF operand also provides the special form 
(MACRF=WL) for creating a BDAM data set. The MACRF operand can be coded in 
any of the forms shown above. The following characters can be coded: 


C 
Specifies that the CNTRL macro instruction is used with the data set. If C is 
specified to be used with a card reader, a CNTRL macro instruction must follow 
every input request. 


Specifies that BSAM is used to create a BDAM data set. This character can be 
specified only in the combination MACRF=WL. 


Specifies that POINT macro instructions are used with the data set being created or 
processed. Specifying P in the MACRF operand also automatically provides the 
capability of using NOTE macro instructions with the data set. For VS2, P must 
not: be coded for SYSIN or SYSOUT data sets. 


R 
Specifies that READ macro instructions are used. 
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WwW 
Specifies that WRITE macro instructions are used. 


Note: Each READ and WRITE macro instruction issued in the problem program must 
be checked for completion by a CHECK macro instruction. | 


Source: The MACRF operand must be specified in the DCB macro instruction. 


NCP=absexp (maximum value is 99) 
The NCP operand specifies the maximum number of READ/WRITE macro 
instructions that will be issued before the first CHECK macro instruction is issued to 
test for completion of the I/O operation. The maximum number may be less than 99 

| depending on the amount of virtual storage available in the region or partition. If 
chained scheduling is specified (OPTCD=C), the value of NCP determines the 
maximum number of channel program segments that can be chained and must be 
specified as more than one. If the NCP operand is omitted, one is assumed. 


Source: The NCP operand can be supplied in the DCB macro instruction, in the DCB 
subparameter of a DD statement, or by the problem program before completion of the 
data control block open exit routine. | 


OPTCD= {B} 
{T} 
{U[C]} 
{C{TI[B}} 
{H[Z][B]} 
{WICI[T][B]} 
{Z[CIIT][B]} 
{Q(CI[BI[T | Z} 


The OPTCD operand specifies the optional services that are used with the BSAM data 
set. Two of the optional services, OPTCD=B and OPTCD=H, cannot be specified in 
the DCB macro instruction. They are requested in the DCB subparameter of a DD 
statement. Since all optional services requests must be supplied by the same source, 
the OPTCD operand must be omitted from the DCB macro instruction if either of 
these options is requested in a DD statement. The following describes the characters 
that can be specified—these characters can be specified in any order (in one of the 

| combinations shown above), and no commas are allowed between characters: 


C 
Requests that chained scheduling be used. OPTCD=C cannot be specified if 
BFTEK=R is specified for the same data control block. Also, chained scheduling 
| cannot be specified for associated data sets or printing on a 3525. OS/VS1 
supports chained scheduling in nonpageable storage only. If chained scheduling is 
requested in pageable storage, the request is ignored and normal scheduling is 
substituted. 


For OS/VS2, chained scheduling is supported for pageable and nonpageable 
storage. 


Requests that ASCII tape records in an input data set be converted to EBCDIC 
code after the input record has been read. Translation is done at CHECK time for 
input. It also requests that an output record in EBCDIC code be converted to 
ASCII code before the record is written. For further information on this 
conversion, see ‘““Variable-Length Records—Format D” in OS/VS Data 
Management Services Guide. 
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T 
Requests the user totaling facility. If this facility is requested, the EXLST operand 
should specify the address of an exit list to be used. T cannot be specified for 
SYSIN and SYSOUT data sets. 


U 
Specified only for a printer with the universal character set (UCS) feature. This 
option unblocks data checks (permits them to be recognized as errors) and allows 
analysis by the appropriate error analysis routine (SYNAD routine). If the U option 
is omitted, data checks are not recognized as errors. 


WwW 
Specifies that the system performs a validity check on each record written on a 
direct-access device. 


For magnetic tape, input only, the Z option requests the system to shorten its 
normal error recovery procedure to consider a data check as a permanent I/O error 
after five unsuccessful attempts to read a record. This option is available only if it is 
selected when the operating system is generated. OPT'CD=Z is used when a tape is 
known to contain errors and there is no need to process every record. The error 
analysis routine (SYNAD) should keep a count of permanent errors and terminate 
processing if the number becomes excessive. 


For direct-access devices only, the Z option requests the system to use the search 
direct option to accelerate the input operations for a data set. OPTCD=Z cannot 
be specified when RECFM=UT, FS, FBT, VS, or VBS. 


Note: The following describes the optional services that can be requested in the DCB 
subparameter of a DD statement. If either of these options is requested, the complete 
OPTCD operand must be supplied in the DD statement. 


B 
If OPTCD=B is specified in the DCB subparameter of a DD statement, it forces 
the end-of-volume (EOV) routine to disregard the end-of-file recognition for 
magnetic tape. When this occurs, the EOV routine uses the number of volume 
serial numbers to determine end of file. 


H 
If OPTCD=H is specified in the DCB subparameter of a DD statement, it specifies 
that the DOS/OS interchange feature is being used with the data set. 


Source: The OPTCD operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, in the data set label for direct-access devices, 
or by the problem program before an OPEN macro instruction is issued to open the 
data set. However, all optional services must be requested from the same source. 
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RECFM= {U[TI[A| MJ} 
{V[B|S|T|BS|BT][A | MJ} 
{D[BI[A]} 


{F[B|S|T|BS|BT][A | Mj} 
The RECEFM operand specifies the record format and characteristics of the data set 
being created or processed. All the record formats shown above can be specified, but 
in those record formats that specify blocked records, the problem program must 
perform the blocking and deblocking of logical records; BSAM recognizes only data 
blocks. The following describes the characters that can be specified: 


A 
Specifies that the records in the data set contain American National Standards 
Institute (ANSD control characters. Refer to Appendix E for a description of 
control characters. 


B 
Specifies that the data set contains blocked records. 


D 
Specifies that the data set contains variable-length ASCII tape records. See 
OPTCD=Q and the BUFOFF operand for a description of how to specify ASCII 
data sets. 


F 
Specifies that the data set contains fixed-length records. 


M 
Specifies that the records in the data set contain machine code control characters. 
Refer to Appendix E for a description of control characters. RECFM=M cannot be 
used with ASCII data sets. 


For fixed-length records, S specifies that the records are written as standard blocks; 
the data set does not contain any truncated blocks or unfilled tracks, with the 
exception of the last block or track in the data set. 


For variable-length records, S specifies that a record can span more than one block. 
Spanned records can be read (reading a BDAM data set) or written (creating a 
BDAM data set) using BSAM. 


Specifies that the track-overflow feature is used with the data set. The 
track-overflow feature allows a record to be written partially on one track of a 
direct-access device and the remainder of the record written on the following track 
(if required). Chained scheduling cannot be used if the track-overflow feature is 
used. 


U 
Specifies that the data set contains undefined-length records. 


V 
Specifies that the data set contains variable-length records. 


Notes: 


e RECFM=V cannot be specified for a card reader data set or an ASCII tape data 
set. 


¢ RECFM=VBS does not provide the spanned record function; if this format is used, 
the problem program must block and segment the records. 
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e RECFM=VS or VBS cannot be specified for a SYSIN data set. 


¢ RECFM=V cannot be used for a 7-track tape unless the data conversion feature 
(TRTCH=C) is used. 


Source: The RECFM operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 


SYNAD=relexp 
The SYNAD operand specifies the address of the error analysis (SYNAD) routine to 
be given control when an uncorrectable input/output error occurs. The contents of 
the registers when the error analysis routine is given control are described in Appendix 
A of this publication. 


The error analysis routine must not use the save area pointed to by register 13, 
because this area is used by the system. The system does not restore registers when it 
regains control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction which uses the address in register 14 to return control to 
the system. If control is returned to the system, the system returns control to the 
problem program and proceeds as though no error had been encountered. 


If the SYNAD operand is omitted, the task is abnormally terminated when an 
uncorrectable input/output error occurs. 


Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error routine address at 
any time. 
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DCB—Construct a Data Control Block (QISAM) 


The data control block for a queued indexed sequential access method (QISAM) data set 
is constructed during assembly of the problem program. The DCB macro instruction 
must not be coded within the first 16 bytes of addressability for the control section 
(CSECT). The DSORG and MACRF operands must be coded in the DCB macro 
instruction, but the other DCB operands can be supplied from other sources. Each 
QISAM DCB operand description contains a heading, “Source.” The information under 
this heading describes the sources which can supply the operand to the data control 
block. 


Before a DCB macro instruction for a QISAM data set is coded, the following 
characteristics of QISAM should be considered: 


e The characteristics of a QISAM data set are established when the data set is created; 
these characteristics cannot be changed without reorganizing the data set. The 
following DCB operands establish the characteristics of the data set and can be coded 
only when creating the data set: BLKSIZE, CYLOFL, KEYLEN, LRECL, NIM, 
OPTCD, RECFM, and RKP. 


e The data set can contain the following record formats: Unblocked fixed-length 
records (F), blocked fixed-length records (FB), unblocked variable-length records 
(V), or blocked variable-length records (VB). 


e QISAM can create an indexed sequential data set (QISAM, load mode), add 
additional data records at the end of the existing data set (QISAM, resume load 
mode), update a record in place, or retrieve records sequentially (QISAM, scan 
mode). : 


e The track-overflow feature cannot be used to create an ISAM data set. 


e When an indexed sequential data set is being created, space for the prime area of the 
data set, the overflow area of the data set, and the cylinder/master index(es) for the 
data set can be allocated on the same or separate volumes. For information about 
space allocation, refer to OS/VSI JCL Reference or OS/VS2 JCL. 


e The system automatically creates one track index for each cylinder in the data set and 
one cylinder index for the entire data set. The DCB NTM and OPTCD operands can 
be specified to indicate that the data set requires a master index(es); the system 
creates and maintains up to three levels of master indexes. OS/VS Data 
Management Services Guide contains additional information about indexes for 
indexed sequential data sets. 


e« A record deletion option can be specified (OPTCD=L) when the ISAM data set is 
created. This option allows a record to be flagged for deletion by placing a 
hexadecimal value of ‘FF’ in the first data byte of the record (first byte of a 
fixed-length record or fifth byte of a variable-length record). Records marked for 
deletion are ignored during sequential retrieval by QISAM. 


¢« Reorganization statistics can be obtained by specifying OPTCD=R when the ISAM 
data set is created. These statistics can be used by the problem program to determine 
the status of the overflow areas allocated to the data set. Reorganization of ISAM 
data sets is described in OS/VS Data Management Services Guide. 


e When an ISAM data set is created, the records must be written with the keys in 
ascending order. 


These characteristics of queued indexed sequential access method data sets are described 
in more detail in OS/VS Data Management Services Guide. 
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The DCB macro for QISAM is written as follows: 


[symbol | | DCB [BFALN={F | D}] 
[BLKSIZE= absexp | 
[BUFCB= relexp | 
[BUFL= absexp | 
[BUFNO= absexp | 
[CYLOFL= absexp | 
[DDNAME= symbol |! 
DSORG={IS | ISU} 
[EODAD= relexp | 
[EXLST= relexp | 
[KEYLEN= absexp | 
[LRECL= absexp | 


MACRF= {(PM)} 
{(PL)} 
i(GMLSiK | I3})} 
i(GL[,S{K | I} }L,PU))} 


INTM= absexp | 
[OPTCD=[T[LI[MI[RILU][WI[Y]] 
[RECFM={V([B] | F[B]}] 

[RKP= absexp | 

[SYNAD= relexp |] 





1This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 


The following describes the DCB operands that can be specified when a QISAM data set 


is being created or processed: 


BFALN={F | D} 


The BFALN operand specifies the alignment of each buffer in the buffer pool when 
the buffer pool is constructed automatically or by a GETPOOL macro instruction. If 
the BFALN operand is omitted, the system provides doubleword alignment for each 
buffer. The following describes the characters that can be specified: 


F 
Specifies that each buffer is on a fullword boundary that is not also a doubleword 
boundary. 


D 
Specifies that each buffer is on a doubleword boundary. 


If the BUILD macro instruction is used to construct the buffer pool, the problem 
program must provide a storage area for the buffers and control buffer alignment. 


Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BLKSIZE=absexp (maximum value is device-dependent) 


The BLKSIZE operand specifies the length, in bytes, for each data block when 
fixed-length records are used, or it specifies the maximum length in bytes, for each 
data block when variable-length records are used. The BLKSIZE operand must be 
specified when an ISAM data set is created. When an existing ISAM data set is 
processed, the BLKSIZE operand must be omitted (it is supplied by the data set 
label). 
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Track capacity of the direct-access device being used must be considered when the 
BLKSIZE for an ISAM data set is specified. For fixed-length records, the sum of the 
key length, data length, and device overhead plus 10 bytes (for ISAM use) must not 
exceed the capacity of a single track on the direct-access device being used. For 
variable-length records the sum of the key length, block-descriptor word length, 
record-descriptor word length, data length, and device overhead plus 10 bytes (for 
ISAM use) must not exceed the capacity of a single track on the direct-access device 
being used. Device capacity and device overhead are described in Appendix C of this 
publication. For additional information about device capacity and space allocation, 
refer to OS/VS Data Management Services Guide. 


If fixed-length records are used, the value specified in the BLKSIZE operand must be 
an integral multiple of the value specified in the LRECL operand. 


Source: When an ISAM data set is created, the BLKSIZE operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the BLKSIZE operand must be omitted from the 
other sources, allowing the data set label to supply the value. 


BUFCB=relexp 
The BUFCB operand specifies the address of the buffer pool control block 
constructed by a BUILD macro instruction. | 


If the system constructs the buffer pool automatically or if the buffer pool is 
constructed by a GETPOOL macro instruction, the system places the address of the 
buffer pool control block into the data control block, and the BUFCB operand should 
be omitted. 


Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


BUFL=absexp (maximum value is 32,760) 
The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool 
when the buffer pool is constructed by a BUILD or GETPOOL macro instruction. 
When the data set is opened, the system computes the minimum buffer length required 
and verifies that the length in the buffer pool control block is equal to or greater than 
the minimum Iength required. The system then inserts the computed length into the 
data control block. 


The BUFL operand is not required for QISAM if the system acquires buffers 
automatically; the system computes the minimum buffer length required and inserts 
the value into the data control block. 


If the buffer pool is constructed with a BUILD or GETPOOL macro instruction, 
additional space is required in each buffer for system use. For a description of the 
buffer length required for various ISAM operations, refer to OS/VS Data 
Management Services Guide. 


Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BUFNO=absexp (maximum value is 255) 
The BUFNO operand specifies the number of buffers to be constructed by a BUILD 
macro instruction, or it specifies the number of buffers to be acquired automatically 
by the system. If the BUFNO operand is omitted, the system automatically acquires 
two buffers. 


If the GETPOOL macro instruction is used to construct the buffer pool, the BUFNO 
operand is not required. 


Macro Instruction Descriptions: DCB—QISAM 103 


Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


CYLOFL=absexp (maximum value is 99) 
The CYLOFL operand specifies the number of tracks on each cylinder that is reserved 
as an overflow area. The overflow area is used to contain records that are forced off 
prime area tracks when additional records are added to the prime area track in 
ascending key sequence. ISAM maintains pointers to records in the overflow area so 
that the entire data set is logically in ascending key sequence. Tracks in the cylinder 
overflow area are used by the system only if OPTCD=Y is specified. For a more 
complete description of cylinder overflow area, refer to the space allocation section of 
OS/VS Data Management Services Guide. 


Source: When an ISAM data set is created, the CYLOFL operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the CYLOFL operand should be omitted, 
allowing the data set label to supply the operand. 


DDNAME=symbol 
The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 


Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 


DSORG={IS | ISU} 
The DSORG operand specifies the organization of the data set and if the data set 
contains any location-dependent information that would make it unmovable. The 
following characters can be specified: 


Is 
Specifies an indexed sequential data set organization. 


ISU 
Specifies an indexed sequential data set that contains location-dependent 
information. ISU can be specified only when an ISAM data set is created. 


Source: The DSORG operand must be specified in the DCB macro instruction. When 
an ISAM data set is created, DSORG=IS or ISU must also be specified in the DCB 
subparameter of the corresponding DD statement. 


EODAD=relexp 
The EODAD operand specifies the address of the routine to be given control when the 
end of an input data set is reached. For ISAM, this operand would apply only to scan 
mode when a data set is open for an input operation. Control is given to this routine 
when a GET macro instruction is issued and there are no more input records to 
retrieve. For additional information on the EODAD routine, see OS/VS Data 
Management Services Guide. 


Source: The EODAD operand can be supplied in the DCB macro instruction or by the 
problem program before the end of the data set is reached. 


EXLST=relexp 
The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required only if the problem program uses the data control block 
exit routine for additional processing or if the DCB ABEND exit is used for ABEND 
condition analysis. 
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Refer to Appendix D of this publication for the format and requirements for exit list 
processing. For additional information about exit list processing, refer to OS/VS 
Data Management Services Guide. 


Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program before the associated exit is required. 


KEYLEN=absexp (maximum value is 255) 
The KEYLEN operand specifies the length, in bytes, of the key associated with each 
record in an indexed sequential data set. When blocked records are used, the key of 
the last record in the block (highest key) is used to identify the block. However, each 
logical record within the block has its own identifying key which ISAM uses to access 
a given logical record. | 


Source: When an ISAM data set is created the KEYLEN operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the KEYLEN operand must be omitted, allowing 
the data set level to supply the key length value. KEYLEN=0 is not valid for an ISAM 
data set. a 


LRECL=absexp (maximum value is device-dependent) 
The LRECL operand specifies the length, in bytes, for fixed-length records, or it 
specifies the maximum length, in bytes, for variable-length records. The value 

_ specified in the LRECL operand cannot exceed the value specified in the BLKSIZE 

operand. When fixed, unblocked records are used and the relative key position (as 
specified in the RKP operand) is zero, the value specified in the LRECL operand 
should include only the data length (the key is not written as part of the fixed, 
unblocked record when RKP=0). | 


The track capacity of the direct-access device being used must be considered if 
maximum length logical records are being used. For fixed-length records, the sum of 
the key length, data length, and device overhead plus 10 bytes (for ISAM use) must 
not exceed the capacity of a single track on the direct-access device being used. For 
variable-length records, the sum of the key length, data length, device overhead, 
block-descriptor-word length, and record-descriptor-word length plus 10 bytes (for 
ISAM use) must not exceed the capacity of a single track on the direct-access device 
being used. Device capacity and device overhead are described in Appendix C of this 
publication. For additional information about device capacity and space allocation, 
refer to OS/VS Data Management Services Guide. 


Source: When an ISAM data set is created, the LRECL operand can be supplied in the 
DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the LRECL operand must be omitted, allowing 
the data set label to supply the value. 
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MACRF= {(PM)} 
{(PL)} 
{(GMI,S{K | 1}])} 
i(GL[,S{K | 1}][,PU})} 


The MACRF operand specifies the type of macro instructions, the transmittal mode, 
and type of search to be used with the data set being processed. The operand can be 
coded in any of the combinations shown above; the following describes the characters 
that can be coded. 


The following characters can be specified only when the data set is being created 
(load mode) or additional records are being added to the end of the data set (resume 
load): 


PL 
Specifies that PUT macro instructions are used in the locate transmittal mode; the 
system provides the problem program with the address of a buffer containing the 
data to be written into the data set. 


PM 
Specifies that PUT macro instructions are used in the move transmittal mode; the 
system moves the data to be written from the problem program work area to the 
buffer being used. 


The following characters can be specified only when the data set is being processed 
(scan mode) or when records in an ISAM data set are being updated in place: 


GL 
Specifies that GET macro instructions are used in the locate transmittal mode; the 
system provides the problem program with the address of a buffer containing the 
logical record read. 


GM 
Specifies that GET macro instructions are used in the move mode; the system 
moves the logical record from the buffer to the problem program work area. 


I 
Specifies that actual device addresses (MBBCCHHR) are used to search for a 
record (or the first record) to be read. 


K 
Specifies that a key or key class is used to search for a record (or the first record) 
to be read. 


PU 
Specifies that PUTX macro instructions are used to return updated records to the 
data set. 


S 
Specifies that SETL macro instructions are used to set the beginning location for 
processing the data set. 


Source: The MACRF operand must be coded in the DCB macro instruction. 


NTM=absexp (maximum value is 99) 
The NIM operand specifies the number of tracks to be created in a cylinder index 
before a higher-level index is created. If the cylinder index exceeds this number, a 
master index is created by the system; if a master index exceeds this number, the next 
level of master index is created. The system creates up to three levels of master 
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indexes. The NIM operand is ignored unless the master index option (OPTCD=M) is 
selected. 


Source: When an ISAM data set is being created, the NIM operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
ISAM data set is being processed, master index information is supplied to the data 
control block from the data set label, and the NTM operand must be omitted. 


OPTCD=([I][L][M][RI[U][WI[Y] 
The OPTCD operand specifies the optional services performed by the system when an 
ISAM data set is being created. The following describes the characters that can be 
specified (these characters can be specified in any order, and no commas are allowed 
between characters): 


I 
Specifies that the system uses the independent overflow areas to contain overflow 
records. Note that it is only the use of the allocated independent overflow area that 
is optional. Under certain conditions, the system designates an overflow area that 
was not allocated for independent overflow by the problem program. See 
‘Allocating Space for an Indexed Sequential Data Set” in OS/VS Data 
Management Services Guide. 


Specifies that the data set will contain records flagged for deletion. A record is 
flagged for deletion by placing a hexadecimal value of ‘FF’ in the first data byte. 
Records flagged for deletion remain in the data set until the space is required for 
another record to be added to the track. Records flagged for deletion are ignored 
during sequential retrieval of the ISAM data set (QISAM, scan mode). This option 
cannot be specified for blocked fixed-length records if the relative key position is 
zero (RKP=0), or it cannot be specified for variable-length records if the relative 
key position is four (RKP=4). 


When an ISAM data set is being processed with BISAM, a record with a duplicate 
key can be added to the data set (WRITE KN macro instruction, only when 
OPTCD=L has been specified and the original record (the one whose key is being 
duplicated) has been flagged for deletion. 


M 
Specifies that the system creates and maintains a master index(es) according to the 
number of tracks specified in the NTM operand. 


R 
Specifies that the system places reorganization statistics in the DCBRORG1, 
DCBRORG2, and DCBRORGS3 fields of the data control block. The problem 
program can analyze these statistics to determine when to reorganize the data set. 
If the OPTCD operand is omitted completely, the reorganization statistics are 
automatically provided. However, if the OPTCD operand is supplied, OPTCD=R 
must be specified to obtain the reorganization statistics. 


U 
Specifies that the system accumulates track index entries in storage and writes them 
as a group for each track of the track index. OPTCD=U can be specified only for 
fixed-length records. The entries are written in fixed-length unblocked format. 


W . 
Specifies that the system performs a validity check on each record written. 
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Specifies that the system uses the cylinder overflow area(s) to contain overflow 
records. If OPTCD=Y is specified, the CYLOFL operand specifies the number of 
tracks to be used for the cylinder overflow area. The reserved cylinder overflow 
area is not used unless OPTCD=Y is specified. 


Source: When an ISAM data set is created, the OPTCD operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before an OPEN macro instruction is issued to open the data set. 
However, all optional services must be requested from the same source. When an 
existing ISAM data set is processed, the optional service information is supplied to the 

| data control block from the data set label, and the OPTCD operand should be 
omitted. 


RECFM={V[B] | F[B]} 
The RECFM operand specifies the format and characteristics of the records in the 
data set. If the RECFM operand is omitted, variable-length records (unblocked) are 
assumed. The following describes the characters that can be specified: 


B 
Specifies that the data set contains blocked records. 


F 
Specifies that the data set contains fixed-length records. 


V 
Specifies that the data set contains variable-length records. 


Source: When an ISAM data set is created, the RECFM operand can be supplied in 
the DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before an OPEN macro instruction is issued to open the data set. 
When an existing ISAM data set is processed, the record format information is 
supplied by the data set label, and the RECFM operand should be omitted. 


RKP=absexp 
The RKP operand specifies the relative position of the first byte of the key within 
each logical record. For example, if RKP=9 is specified, the key starts in the tenth 
byte of the record. The delete option (OPTCD=L) cannot be specified if the relative 
key position is the first byte of a blocked fixed-length record or the fifth byte of a 
variable-length record. If the RKP operand is omitted, RKP=0 is assumed. 


If unblocked fixed-length records with RKP=0 are used, the key is not written as a 
part of the data record, and the delete option can be specified. If blocked fixed-length 
records are used, the key is written as part of each data record; either RKP must be 
greater than zero or the delete option must not be used. 


If variable-length records (blocked or unblocked) are used, RKP must be four or 
greater if the delete option is not specified; if the delete option is specified, RKP must 
be specified as five or greater. The four additional bytes allow for the block descriptor 
word in variable-length records. 


Source: When an ISAM data set is created, the RKP operand can be supplied in the 
DCB macro instruction, in the DCB subparameter of a DD statement, or by the 
problem program before completion of the data control block exit routine. When an 
existing ISAM data set is processed, the RKP information is supplied by the data set 
label and the RKP operand should be omitted. 
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SYNAD=relexp 
The SYNAD operand specifies the address of the error analysis routine given control 
when an uncorrectable input/output error occurs. The contents of the registers when 
the error analysis routine is given control are described in Appendix A of this 
publication. 


The error analysis routine must not use the save area pointed to by register 13, 
because this area is used by the system. The system does not restore registers when it 
regains control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction which uses the address in register 14 to return control to 
the system. When control is returned in this manner, the system returns control to the 
problem program and proceeds as though no error had been encountered; if the error 
analysis routine continues processing, the results may be unpredictable. 


For additional information on error analysis routine processing for indexed sequential 
data sets, see OS/VS Data Management Services Guide. 


Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error analysis routine 
address at any time. 
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DCB—Construct a Data Control Block (QSAM) 


The data control block for the queued sequential access method (QSAM) is constructed 
during assembly of the problem program. The DSORG and MACRF operands must be 
coded in the DCB macro instruction, but the other DCB operands can be supplied, to the 
data control block, from other sources. Each DCB operand description contains a 
heading, ‘“‘Source.’’The information under this heading describes the sources from which 
the operand can be supplied. 


Before a DCB macro instruction for creating or processing a QSAM data set is coded, 
the following characteristics of QSAM data sets should be considered. 


e All record formats can be processed. 
e Automatic blocking and deblocking of records is provided. 


e Automatic buffer control is provided; this function fills input buffers when they are 
empty and writes output buffers when they are full. 


e A logical record interface is provided; a GET macro instruction retrieves the next 
sequential logical record from the input buffer, and a PUT macro instruction places 
the next sequential logical record in the output buffer. 


¢ I/O operations are synchronized automatically. 


¢« Four transmittal modes (move, locate, data, and substitute) are provided. These 
transmittal modes provide flexibility in buffer management and data movement 
between buffers. 


e Keys for direct-access device records cannot be read or written using QSAM. 


e Specifying the DEVD operand in the DCB macro instruction can cause the program to 
be device-dependent. 


These characteristics of queued sequential access method data sets are described in more 
detailin OS/VS Data Management Services Guide. 


For information on additional operands for the DCB macro for the 3890, see JBM 
3890 Document Processor Machine and Programming Description. 
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The DCB macro for OQSAM is written as follows: 


[symbol] | DCB [BFALN={F | D}] 
[BFTEK={S | E| A}] 
[BLKSIZE= absexp | 
[BUFCB= relexp | 
[BUFL= absexp | 
[BUFNO= absexp | 
[BUFOFF={ absexp | L}] 
[DDNAME= symbol |! 


[DEVD= {DA} 


[TA ee. 
[,DEN={0| 1/213] 43] 
[,TRTCH={C|E|ET|T}}} 


{PT | 
[,CODE={A|B|C|FII|N|T}]} 


{PR 
|, PRTSP={0 | 1|2|33]} 


{PC 
LMODE=[C | E][R]] 
[,STACK={1|2}]. 
[,.FUNC={I| P| PW[XT]|R| RP[D] | RW[T] | 
RWP([XT)[D] | WIT]}}} 





{RD 
|, MODE=[C | E][0 | RJ] 
[,STACK={1 | 23] 
[| FUNC={I| P| PW[XT] | R | RP[D] | RWIT]| 
RWP[XT][D] | WIT}H} 


DSORG={PS | PSU} 
[EODAD=relexp | _ 
[EROPT={ACC | SKP | ABE}] 
[EXLST= relexp ] | 
[LRECL={ absexp | X}] 


MACRF= {(Gi{M|L|T|D}[C])} 
i(P{M | L|T|D}[C})} 
{(GiM|L| T | D3{C],PiM [L|T{|DI[C}} 


1This parameter must be supplied before an OPEN macro is issued for this DCB; 
it cannot be supplied in the open exit routine. 


Continued on next page. 
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[OPTCD= {B} 
iT} 
{U[C]} 
iC[T][B]} 
{H[Z][B]} 
{WICI[TI[B]} 


{Z[C][TI[B]} 
{Q(C][BIT | Z]}] 
[RECFM={U[T][A | M]} 
{V[B[S][T] | S[T] | TILA | MJ} 
{D[B][A]} 
{F[B|S|T|BS|BTI[A| M]}] 
[SYNAD= relexp | 





The following describes the operands that can be specified in the DCB macro instruction 
for a QSAM data set: 


BFALN={F | D}: 
The BFALN operand specifies the boundary alignment of each buffer in the buffer 
pool when the buffer pool is constructed automatically or by a GETPOOL macro 
instruction. If the BFALN operand is omitted, the system provides doubleword 
alignment for each buffer. 


If the data set being created or processed contains ASCII tape records with a block 
prefix, the block prefix is entered at the beginning of the buffer, and data alignment 
depends on the length of the block prefix. For a description of how to specify the 
block prefix length, refer to the BUFOFF operand. 


The following describes the characters that can be specified: 


F 
Specifies that each buffer is on a fullword boundary that is not also a doubleword 
boundary. 


D 
Specifies that each buffer is on a doubleword boundary. 


When exchange buffering (BFTEK=E) is specified and the records are in blocked 
fixed-length format, each buffer segment is aligned as specified in the BFALN 
operand (VS1 systems only). 


If the BUILD macro instruction is used to construct the buffer pool, the problem 
program must control buffer alignment. | 


Source: The BFALN operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFALN and BFTEK operands are 
specified, they must be supplied from the same source. 
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BFTEK={S|E| A} 
The BFTEK operand specifies the buffering technique that is used when the QSAM 
data set is created or processed. If the BFTEK operand is omitted, simple buffering is 
assumed. The following describes the characters that can be specified: 


S 
Specifies that simple buffering is used. 


E 
Specifies that exchange buffering is used. Exchange buffering can be used only with 
record formats (RECFM operand) F, FB, FBS, or FS; the track-overflow feature 
cannot be used with exchange buffering. If exchange buffering is used with ASCII 
tape records, the BUFOFF operand must be zero (no block prefix). BFTEK=E is 
ignored by VS2 systems. 


Specifies that a logical record interface is used for variable-length spanned records. 
When BFTEK=A is specified, the Open routine acquires a record area equal to the 
length specified in the LRECL field plus 32 additional bytes for control 
information. When a logical record interface is requested, the system uses the 
simple buffering technique. 


To use the simple or exchange buffering technique efficiently, the user should be 
familiar with the four transmittal modes for QSAM and the buffering techniques as 
described in OS/VS Data Management Services Guide. 


Source: The BFTEK operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. If both the BFTEK and BFALN operands are 
specified, they must be supplied from the same source. 


BLKSIZE=absexp (maximum value is 32,760) 
The BLKSIZE operand specifies the length, in bytes, of a data block for fixed-length 
records, or it specifies the maximum length, in bytes, of a data block for 
variable-length or undefined-length records. 


The actual value that can be specified in the BLKSIZE operand depends on the device 
type and record format being used. Device capacity is shown in Appendix C of this 
publication. For additional information about device capacity, refer to OS/VS Data 
Management Services Guide. For direct-access devices when the track-overflow 
feature is used or variable-length spanned records are being processed, the BLKSIZE 
operand can be up to the maximum value. For other record formats used with 
direct-access devices, the value specified in the BLKSIZE operand cannot exceed the 
capacity of a single track. 


Since QSAM provides a logical record interface, the device capacities shown in 
Appendix C also apply to a maximum length logical record. One exception to the 
device capacity for a logical record is the size of variable-length spanned records. 
Their length can exceed the value specified in the BLKSIZE operand (see the 
description of the LRECL operand). 


If fixed-length records are used for a SYSOUT data set, the value specified in the 
BLKSIZE operand must be an integral multiple of the value specified in the LRECL 
operand; otherwise, the system will adjust the block size downward to the nearest 
multiple. If the records are unblocked fixed-length records, the value specified in the 
BLKSIZE operand must equal the value specified in the LRECL operand if the 
LRECL operand is specified. 


2 
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If variable-length records are used, the value specified in the BLKSIZE operand must 
include the data length (up to 32,756 bytes) plus four bytes required for the block 
descriptor word (BDW). For format-D variable-length records, the minimum 
BLKSIZE is 18 bytes and the maximum is 2,048 bytes. 


If ASCII tape records with a block prefix are processed, the value specified in the 
BLKSIZE operand must also include the length of the block prefix. 


If variable-length spanned records are used, the value specified in the BLKSIZE 

operand can be the best one for the device being used or the processing being done. 

When unit record devices (card or printer) are used, the system assumes records are 

unblocked; the value specified for the BLKSIZE operand is equivalent to one print 

line or one card. A logical record that spans several blocks is written one segment at a 
time. 


If undefined-length records are used, the problem program can insert the actual record 
length into the DCBLRECL field. See the description of the LRECL operand. 


Source: The BLKSIZE operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 


BUFCB=relexp 
The BUFCB operand specifies the address of the buffer pool control block 
constructed by a BUILD or BUILDRCD macro instruction. 


If the buffer pool is constructed automatically or by a GETPOOL macro instruction, 
the system places the address of the buffer pool control block into the data control 
block, and the BUFCB operand should be omitted. 


Source: The BUFCB operand can be supplied in the DCB macro instruction or by the 
problem program before completion of the data control block exit routine. 


BUFL=absexp (maximum value is 32,760) 
The BUFL operand specifies the length, in bytes, of each buffer in the buffer pool 
when the buffer pool is acquired automatically. The system acquires buffers with a 
length equal to the value specified in the BLKSIZE operand if the BUFL operand is 
omitted; if the problem program requires larger buffers, the BUFL operand is 
required. If the data set is for card image mode, the BUFL operand is specified as 160 
bytes. The description of the DEVD operand contains a description of card image 
mode. 


If the data set contains ASCII tape records with a block prefix, the value specified in 
the BUFL operand must also include the length of the block prefix. 


If the buffer pool is constructed by a BUILD, BUILDRCD, or GETPOOL macro 
instruction, the BUFL operand is not required. 


Source: The BUFL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BUFNO=absexp (maximum value is 255) 
The BUFNO operand specifies the number of buffers in the buffer pool constructed 
by a BUILD or BUILDRCD macro instruction, or it specifies the number of buffers 
to be acquired automatically. If chained scheduling is specified, the value of BUFNO 
determines the maximum number of channel program segments that can be chained 
and must be specified as more than one. If the BUFNO operand is omitted and the 
buffers are acquired automatically, the system acquires three buffers if the device is a 
2540 card read punch or two buffers for any other device type. For VS2, the system 
acquires five buffers. : 
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If the buffer pool is constructed by a GETPOOL macro instruction, the BUFNO 
operand is not required. 


Source: The BUFNO operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before completion 
of the data control block exit routine. 


BUFOFF={ absexp | L} 
The BUFOFF operand specifies the length, in bytes, of the block prefix used with 
ASCII tape data sets. When QSAM is used to read ASCII tape records, only the data 
portion (or its address) is passed to the problem program; the block prefix is not 
available to the problem program. Block prefixes (except BUFOFF=:L) cannot be 
included in QSAM output records. The following can be specified in the BUFOFF 
operand: 


absexp 
Specifies the length, in bytes, of the block prefix. This value can be from 0 to 99 
for an input data set. The value must be 0 for writing an output data set with 
fixed-length or undefined-length records. 


Specifies that the block prefix is 4 bytes long and contains the block length. 
BUFOFF=L is used when format-D records (ASCII) are processed. QSAM uses 
the four bytes as a block-descriptor word (BDW). For further information on this 
operand, see ““Variable-Length Records—Format D”’ in OS/VS Data 
Management Services Guide. 


Source: The BUFOFF operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program before an OPEN 
macro instruction is issued to open the data set. BUFOFF=absexp can also be 
supplied by the label of an existing data set; BUFOFF=L cannot be supplied by the 
label of an existing data set. 


DDNAME=symbol 
The DDNAME operand specifies the name used to identify the job control language 
data definition (DD) statement that defines the data set being created or processed. 


Source: The DDNAME operand can be supplied in the DCB macro instruction or by 
the problem program before an OPEN macro instruction is issued to open the data 
set. 


DEVD={DA|TA|PT|PR|PC|RD}{[, options] 
The DEVD operand specifies the device type on which the data set can or does reside. 
The device types above are shown with the optional operand(s) that can be coded 
when a particular device is used. The devices are listed in order of 
device-independence. For example, if DEVD=DA is coded in a DCB macro 
instruction (or the DEVD operand is omitted, which causes a default to DA), the data 
control block constructed during assembly could later be used for any of the other 
devices, but if DEVD=RD is coded, the data control block can be used only with a 
card reader or card reader punch. Unless you are certain that device interchangeability 
is not required, you should either code DEVD=DA or omit the operand and allow it to 
default to DA. 


If system input is directed to an intermediate storage device, the DEVD operand is 
omitted, and the job control language for the problem program must designate the 
system input to be used. Similarly, if system output is directed to an intermediate 
storage device, the DEVD operand is omitted, and the job control language for the 
problem program must designate the system output to be used. 
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If DEVD=PT is coded, the DCB macro should not be coded within the first 8 bytes 
of addressability for the control section (CSECT). If DEVD=PR, PC, or RD is 
coded, the DCB macro should not be coded within the first 16 mie of addressability 
for the control section. — 


The DEVD operand is discussed below according to individual device type: 


DEVD=DA | - 
Specifies that the data control block can be used for a direct-access device (or any 
of the other device types described following DA). 


DEVD=TA 
[ DEN={0|1]|2|3]| 43] 
[,TRTCH={C | E| ET | T}] 
Specifies that the data control block can be used for a magnetic tape data set (or 
any of the other device types described following TA). If TA is coded, the following 
optional operands can be coded: 


DEN={0[1| 2/3] 4} 
The DEN operand specifies the recording density in the number of bits-per-inch 
per track as shown in the following chart: 
Recording Density 
DEN 7-Track Tape 9-Track Tape 


0 200 _— 
1 556 —_ 

2 800 800. (NRZI)1 
3 aa 1600 (PE)2 
4 jo 6250 (GCR)3 


1 NRZI is for non-return-to-zero inverted mode 
PE is for phase encoded mode 
3 GCR is for group coded recording mode 


Note: Specifying DEN=0 for a 7-track 3420 tape attached to a 3803-1 will 
result in 556 bits-per-inch recording, but corresponding messages and tape labels 
will indicate 200 bits-per-inch recording density. 


If the DEN operand is not supplied by any source, the highest applicable density 
is assumed. 


TRTCH={C|E|ET|T} 
The TRTCH operand specifies the recording technique for 7-track tape. One of 
the above character combinations can be coded. If the TRTCH operand is 
omitted, odd parity with no translation or conversion is assumed. The following 
describes the characters that can be specified: 


C 
Specifies that the data-conversion feature is used with odd parity and no 
translation. 


E ; 
Specifies even parity with no translation or conversion. 


ET 
Specifies even parity with BCDIC to EBCDIC translation required, but no 
data-conversion feature. 


T 
Specifies that BCDIC to EBCDIC translation is required with odd parity and 
no data-conversion feature. 
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DEVD=PT 
[,CODE={A|B|C|F|I|N|TH 
Specifies that the data control block is used for a paper tape device (or any of the 
other devices following PT). If PT is coded, the following optional operand can be 
coded: 


CODE={A|B|C|F|I|N|T} 
The CODE operand specifies the code in which the data was punched. The 
system converts these codes to EBCDIC code. If the CODE operand is not 
supplied by any source, CODE=I is assumed. The following describes the 
characters that can be specified: 


A 
Specifies 8-track tape in ASCII code. 


B 
Specifies Burroughs 7-track tape. 


C 
Specifies National Cash Register 8-track tape. 


F 
Specifies Friden 8-track tape. 


Specifies IBM BCD perforated tape and transmission code with 8-tracks. 


N 
Specifies that no conversion is required. 


T 
Specifies Teletype! 5-track tape. 


DEVD=PR 
[,PRTSP={0|1| 2133] 
Specifies that the data control block is used for an on-line printer (or any of the 
other device types following PR). If PR is coded, the following optional operand 
can be coded: 


PRTSP={0|1|2]| 3} 
The PRTSP operand specifies the line spacing on the printer. This operand is not 
valid if the RECFM operand specifies either machine (RECFM=M) or ANSI 
(RECFM=A) control characters. If the PRTSP operand is not specified from 
any source, one is assumed. The following describes the characters that can be 
specified: 


0 
Specifies that spacing is suppressed (no space). 


1 
Specifies single-spacing. 


2 
Specifies double-spacing (one blank line between printed lines). 


3 | 
Specifies triple-spacing (two blank lines between printed lines). 


ITrademark of Teletype Corporation. 
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DEVD=PC | 
[MODE=[C | E][R]] 
[ STACK={1 | 2}] 
[,FUNC={I| P| PW[XT] | R | RP[D] | RW[T] | RWP[XT][D] | W[T]}] 
Specifies that the data control block is used for a card punch (or any of the other 
device types following PC). If PC is coded, the following optional operands can be 
specified: 


MODE=[C | E][R] 
The MODE operand specifies the mode of operation for the card punch. If the 
MODE operand is omitted, E is assumed. The following describes the characters 
that can be specified: 


C F 
Specifies that the cards are punched in card image mode. In card image mode, 
the 12 rows in each card column are punched from two consecutive bytes of 
virtual storage. Rows 12 through 3 are punched from the low-order 6 bits of 
one byte, and row 4-9 are punched from the 6 low-order bits of the following 
byte. 


E 
Specifies that cards are punched in EBCDIC code. 


R 
Specifies that the program runs in read-column-eliminate mode (3505 card 
reader or 3525 card punch, read feature). 


Note: If the MODE operand is specified in the DCB subparameter of a DD 
statement, either C or E must be specified if R is specified. 


STACK={1 | 2} 
The STACK operand specifies the stacker bin into which the card is placed after 
punching is completed. If this operand is omitted, stacker number 1 is used. The 
following describes the characters that can be specified: 


1 
Specifies stacker number 1. 


2 
Specifies stacker number 2. 


FUNC={I| P| PW[XT]|R|RP[D] | RW[T] | RWP[XT][D] | W[T]} 
The FUNC operand defines the type of 3525 card punch data sets that are used. 
If the FUNC operand is omitted from all sources, a data set opened for input 
defaults to read only, and a data set opened for output defaults to punch only. 
The following describes the characters that can be specified in the FUNC 
operand: 


D ; 
Specifies that the data protection option is to be used. The data protection 
option prevents punching information into card columns that already contain 
data. When the data protection option is used, an 80-byte data protection 
image (DPI) must have been previously stored in SYS1.IMAGELIB. Data 
protection applies only to the output punch portion of a read and punch or 
read, punch, and print operation. 


Specifies that the data in the data set is to be punched into cards and printed 
on the cards; the first 64 characters are printed on line 1 of the card and the 
remaining 16 characters are printed on line 3. 
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P 
Specifies that the data set is for punching cards. See the description of the 
character X for associated punch and print data sets. 


R 
Specifies that the data set is for reading cards. 


T 
Specifies that the two-line option is used. The two-line print option allows 
two lines of data to be printed on the card (lines 1 and 3). If T is not 
specified, the multiline print option is used; this allows printing on all 25 
possible print lines. In either case, the data printed may be the same as the 
data punched in the card, or it may be entirely different data. 


WwW 
Specifies that the data set is for printing. See the description of the character 
X for associated punch and print data sets. 


xX 
Specifies that an associated data set is opened for output for both punching 
and printing. Coding the character X is used to distinguish the 3525 printer 
output data set from the 3525 punch output data set. 


Note: If data protection is specified, the data protection image (DPI) must be 
specified in the FCB subparameter of the DD statement for the data set. 


DEVD=RD 
|, MODE=[C | E][O | R]] 
[ STACK={1 | 23] 
| FUNC={I| P| PW[XT] | R | RP[D] | RWIT] | RWP[XT][D] | WIT} 


RD 
Specifies that the data control block is used with a card reader or card read punch. 
If RD is specified, the data control block cannot be used with any other device 
type. When RD is coded, the following optional operands can be specified: 


MODE=[C | E][O | R] 
The MODE operand specifies the mode of operation for the card reader. The 
following describes the characters that can be specified: 


C 
Specifies that the cards to be read are in card image mode. In card image 
mode, the 12 rows of each card column are read into two consecutive bytes of 
virtual storage. Rows 12 through 3 are read into the low-order 6 bits of one 
byte, and rows 4 through 9 are read into the low-order 6 bits of the following 
byte. 


E 
Specifies that the cards to be read contain data in EBCDIC code. 


O 
Specifies that the program runs in optical mark read mode (3505 card reader). 


R 
Specifies that the program runs in read-column-eliminate mode (3505 card 
reader and 3525 card punch, read feature). 


Note: If the MODE operand for a 3505 or 3525 is specified in the DCB 
subparameter of a DD statement, either C or E must be specified if R or O is 
specified. 
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STACK={1 | 2} 
The STACK operand specifies the stacker bin into which the card is placed after 
reading is completed. If this operand is omitted, stacker number 1 is used. The 
following describes the characters that can be specified: 


1 
Specifies stacker number 1. 


2 
Specifies stacker number 2. 


FUNC={I| P| PW[XT] | R | RP[D] | RW[T] | RWP[XT][D] | W[T]} 
The FUNC operand defines the type of 3525 card punch data sets that are used. 
If the FUNC operand is omitted from all sources, a data set opened for input 
defaults to read only, and a data set opened for output defaults to punch only. 
The following describes the characters that can be specified in the FUNC 
operand: — | 


D 
Specifies that the data protection option is to be used. The data protection 
option prevents punching information into card columns that already contain 
data. When the data protection option is used, an 80-byte data protection 
image (DPI) must have been previously stored in SYS1.IMAGELIB. Data 
protection applies only to the output punch portion of a read and punch or 
read, punch, and print operation. 


Specifies that the data in the data set is to be punched into cards and printed 
on the cards; the first 64 characters are printed on line 1 of the card and the 
remaining 16 characters are printed on line 3. 


Specifies that the data set is for punching cards. See the description of the 
character X for associated punch and print data sets. 


Specifies that the data set is for reading cards. 


Specifies that the two-line option is used. The two-line print option allows 
two lines of data to be printed on the card (lines 1 and 3). If T is not 
specified, the multiline print option is used; this allows printing on all 25 
possible print lines. In either case, the data printed may be the same as the 
data punched in the card, or it may be entirely differnt data. 


W 
Specifies that the data set is for printing. See the description of the character 
X for associated punch and print data sets. 


x 
Specifies that an associated data set is opened for output for both punching 
and printing. Coding the character X is used to distinguish the 3525 printer 
output data set from the 3525 punch output data set. 


Note: If data protection is specified, the data protection image (DPI) must be 
specified in the FCB subparameter of the DD statement for the data set. 


Source: The DEVD operand can be supplied only in the DCB macro instruction. 
However, the optional operands can be supplied in the DCB macro instruction, the 
DCB subparameter of a DD statement, or by the problem program before 
completion of the data control block exit routine. , 
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DSORG={PS | PSU} 
The DSORG operand specifies the organization of the data set and if the data set 
contains any location-dependent information that would make it unmovable. The 
following can be specified in the DSORG operand: 


PS 
Specifies a physical sequential data set. 


PSU 
Specifies a physical sequential data set that contains location-dependent 
information. 


Source: The DSORG operand must be coded in the DCB macro instruction. 


EODAD=relexp 
The EODAD operand specifies the address of the routine given control when the end 
of an input data set is reached. Control is given to this routine when a GET macro 
instruction is issued and there are no additional records to be retrieved. If the record 
format is RECFM=FS or FBS the end-of-data condition is sensed when file mark is 
read or if more data is requested after reading a truncated block. If the end of the data 
set has been reached but no EODAD address has been supplied to the data control 
block, or if a GET macro instruction is issued after an end-of-data exit is taken, the 
task is abnormally terminated. For additional information on the EODAD routine, see 
OS/VS Data Management Services Guide. 


Source: The EODAD operand can be supplied in the DCB macro instruction or by the 
problem program before the end of the data set has been reached. 


EROPT={ACC | SKP | ABE} 
The EROPT operand specifies the action taken by the system when an uncorrectable 
input/output data validity error occurs and no error analysis (SYNAD) routine 
address has been provided, or it specifies the action taken by the system after the 
error analysis routine has returned control to the system with a RETURN macro 
instruction. The specified action is taken for input operations or for output operations 
to a printer. 


Uncorrectable input/output errors resulting from channel operations or direct-access 
operations that make the next record inaccessible cause the task to be abnormally 
terminated regardless of the action specified in the EROPT operand. 


ACC 
Specifies that the problem program accepts the block causing the error. This action 
can be specified when a data set is opened for INPUT, RDBACK, UPDAT, or 
OUTPUT (OUTPUT applies to printer data sets only). 


SKP 
Specifies that the block that caused the error is skipped. Specifying SKP also causes 
the buffer associated with the data block to be released. This action can be 
specified when a data set is opened for INPUT, RDBACK, or UPDAT. 


ABE 
Specifies that the error results in the abnormal termination of the task. This action 
can be specified when the data set is opened for INPUT, OUTPUT, RDBACK, or 
UPDAT. 


If the EROPT operand is omitted, the ABE action is assumed. 


Source: The EROPT operand can be specified in the DCB macro instruction, in the 
DCB subparameter of a DD statement, or by the problem program at any time. The 
problem program can also change the action specified at any time. 
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EXLST=relexp 
The EXLST operand specifies the address of the problem program exit list. The 
EXLST operand is required if the problem program requires additional processing for 
user labels, user totaling, data control block exit routine, end-of-volume, block count 
exits, to define a forms control buffer (FCB) image, or to use the DCB ABEND exit 
for ABEND condition analysis. 


Refer to Appendix D of this publication for the format and requirements of exit list 
processing. For additional information about exit routine processing, refer to OS/VS 
Data Management Services Guide. 


Source: The EXLST operand can be supplied in the DCB macro instruction or by the 
problem program any time before the exit is required by the problem program. 


LRECL={ absexp | X} 
The LRECL operand specifies the length, in bytes, for fixed-length logical records, or 
it specifies the maximum length, in bytes for variable-length or undefined-length 
(output only) logical records. The value specified in the LRECL operand cannot 
exceed the value specified in the BLKSIZE operand except when variable-length 
spanned records are used. 


For fixed-length records that are unblocked, the value specified in the LRECL 
operand must be equal to the value specified in the BLKSIZE operand. For blocked 
fixed-length records, the value specified in the LRECL operand must be evenly 
divisible into the value specified in the BLKSIZE operand. 


For variable-length logical records, the value specified in the LRECL operand must 
include the maximum data length (up to 32,752) plus four bytes for the 
record-descriptor word (RDW). 


For undefined-length records, the problem program must insert the actual logical 
record length into the DCBLRECL field before writing the record, or the maximum 
length record will be written. 


For variable-length spanned records, the logical record length (LRECL) can exceed 
the value specified in the BLKSIZE operand, and a variable-length spanned record 
can exceed the maximum block size (32,760 bytes). When the logical record length 
exceeds the maximum block size, LRECL=X must be specified and GET or PUT 
locate mode must be used. 


Source: The LRECL operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 


MACRF= {(GiM|L|T|D}[C)} 
{(P{M|L|T|D}[c})} 
{(G{M|L|T| D3[C],P{M | L|T | D3[C)} 


The MACRF operand specifies the type of macro instructions (GET, PUT or PUTX, 
CNTRL, RELSE, and TRUNC) and the transmittal modes (move, locate, data, and 
substitute) that are used with the data set being created or processed. The operand 
can be coded in any of the combinations shown above; the following describes the 
characters that can be coded: 


C 
_ Specifies that the CNTRL macro instruction is used with the data set. If the 
CNTRL macro instruction is specified, the data set should be for a card reader 
(stacker selection) or printer (carriage and spacing control). The CNTRL option 
can be specified with GET in the move mode only. 
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D ~ 
Specifies that the data transmittal mode is used (only the data portion of a record is 
moved to or from the work area). Data mode is used only with variable-length 
spanned records. 


G 
Specifies that GET macro instructions are used. Specifying G also provides the 
routines that allow the problem program to issue RELSE macro instructions. 


L , 
Specifies that the locate transmittal mode is used; the system provides the address 
of the buffer containing the data. 


M | 
Specifies that the move transmittal mode is used; the system moves the data from 
the buffer to the work area in the problem program. 


P 
Specifies that PUT or PUTX macro instructions are used. Specifying P also 
provides the routines that allow the problem program to issue TRUNC macro 
instructions. 


T 
Specifies that the substitute transmittal mode is used; the system substitutes a 
buffer for a work area contained in the problem program. | 


Note: For data sets on paper tape that are processed by QSAM, only MACRF=(GM) 
can be specified. 


Source: The MACRF operand can be applied only in the DCB macro instruction. 
OPTCD= {B} 
iT} 
{U[C]} 
{C[T][B]3 
{HIZB} 
{WICITI[B]} 
{Z[CITIB}3 
{QICIBIIT | ZI} 


The OPTCD operand specifies the optional services used with the QSAM data set. 
Two of the optional services, OPTCD=B and OPTCD=H, cannot be specified in the 
DCB macro instruction. They are requested in the DCB subparameter of a DD. 
statement. Since all optional services codes must be supplied by the same source, the 
OPTCD operand must be omitted from the DCB macro instruction if either of these 
options is requested in a DD statement. The following describes the characters that 
can be specified: 7 


C : 

Requests that chained scheduling be used. OPTCD=C cannot be specified when 

either BFTEK=A or BFTEK=R is specified for the same data control block. Also, 

chained scheduling cannot be specified for associated data sets or printing on a 

| 3525. OS/VS1 supports chained scheduling in nonpageable storage only. If chained 
scheduling is requested in pageable storage, the request is ignored and normal 
scheduling is substituted. 
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For OS/VS2, chained scheduling is supported for pageable and nonpageable 
storage. 


Q 
Requests that ASCII tape records in an input data set be converted to EBCDIC 
code when the input record has been read, or an output record in EBCDIC code be 
converted to ASCII code before the record is written. For further information on 
this conversion, see ‘‘Variable-Length Records—Format D” in OS/VS Data 
Management Services Guide. 


Requests the user totaling facility. If this facility is requested, the EXLST operand 
should specify the address of an exit list to be used. T cannot be specified for a 
SYSIN or SYSOUT data set. 


U 
Specified only for a printer with the universal-character-set feature. This option 
unblocks data checks (permits them to be recognized as errors) and allows analysis 
by the appropriate error analysis routine (SYNAD routine). If the U option is 
omitted, data checks are not recognized as errors. 


WwW 


Specifies that the system performs a validity check for each record written on the 
direct-access device being used. 


For magnetic tape, input only, the Z option requests the system to shorten its 
normal error recovery procedure to consider a data check as a permanent I/O error 
after five unsuccessful attempts to read a record. This option is available only if it is 
selected when the operating system is generated. OPTCD=Z is used when a tape is 
known to contain errors and there is no need to process every record. The error 
analysis routine (SYNAD) should keep a count of permanent “errors and terminate 
processing if the number becomes excessive. 


For direct-access devices only, the Z option requests the system to use the search 
direct option to accelerate the input operations for a data set. OPTCD=Z cannot 
be specified when RECFM=UT, FS, FBT, VS, or VBS. 


Note: The following describes the optional services that can be specified in the DCB 
subparameter of a DD statement. If either of these options is requested, the complete 
OPTCD operand must be supplied in the DD statement. 


B 
If OPTCD=B is specified in the DCB subparameter of a DD statement, it forces 
the end-of-volume (EOV) routine to disregard the end-of-file recognition for 
magnetic tape. When this occurs, the EOV routine uses the number of volume 
serial numbers to determine end of file. For an input data set on a standard labeled 
(SL or AL) tape, the EOV routine will treat EOF labels as EOV labels until the 
volume serial list is exhausted. When all the volumes have been read, control is 
passed to the user’s end-of-data routine. This option allows SL or AL tapes to be 
read out of volume sequence or to be concatenated to another tape using one DD 
statement. 


H 
If OPTCD=H is specified in the DCB subparameter of a DD statement, it specifies 
that the DOS/OS interchange feature is being used with the data set. 
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RECFM= {U[TI[A | M]} 
{V[BIS][T] | S(T] | TILA | MJ} 
{D[B][A]} 
tF(B|S|T|BS|BTJ[A | MJ} 
The RECFM operand specifies the record format and characteristics of the data set 


being created or processed. All record formats can be used in QSAM. The following 
describes the characters that can be specified: 


A | 
Specifies that the records in the data set contain American National Standards 
Institute (ANSI) control characters. Refer to Appendix E for a description of 
control characters. 


B 
Specifies that the data set contains blocked records. 


D 
Specifies that the data set contains variable-length ASCII tape records. See 
OPTCD=Q and the BUFOFF operand for a description of how to specify ASCII 
data sets. 


F 
Specifies that the data set contains fixed-length records. 


M 
Specifies that the records in the data set contain machine code control characters. 
Refer to Appendix E for a description of control characters. RECFM=M< cannot be 
used with ASCII data sets. 


For fixed-length records, S specifies that the records are written as standard blocks; 
the data set does not contain any truncated blocks or unfilled tracks, with the 
exception of the last block or track in the data set. 


For variable-length records, S specifies that a record can span more than one block. 
If spanned records are used, exchange buffering (BFTEK=E) cannot be specified. 


Do not code S to retrieve records from a data set that was created using a RECFM 
other than standard. 


Specifies that the track-overflow feature is used with the data set. The 
track-overflow feature allows a record to be written partially on one track and the 
remainder of the record on the following track (if required). Chained scheduling 
(OPTCD=C) and exchange buffering (BFTEK=E) cannot be used if the 
track-overflow feature is used. 


U 
Specifies that the data set contains undefined-length records. 


Vv 
Specifies that the data set contains variable-length records. 


Notes: 


e RECFME=V cannot be specified for a card reader data set or an ASCII tape data 
set. 


e RECFM=VS or VBS cannot be specified for a SYSIN data set. 
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Source: The RECFM operand can be supplied in the DCB macro instruction, in the 
DCB subparameter of a DD statement, by the problem program before completion of 
the data control block exit routine, or by the data set label of an existing data set. 


SYNAD =relexp 
The SYNAD operand specifies the address of the error analysis routine given control 
when an uncorrectable input/output error occurs. The contents of the registers when 
the error analysis routine is given control are described in Appendix A of this 
publication. 


The error analysis routine must not use the save area pointed to by register 13, 
because this area is used by the system. The system does not restore registers when it 
regains control from the error analysis routine. The error analysis routine can issue a 
RETURN macro instruction that uses the address in register 14 to return control to 
the system. 


If the error condition was the result of a data-validity error, the control program takes 
the action specified in the EROPT operand; otherwise, the task is abnormally 
terminated. The control program takes these actions when the SYNAD operand is 
omitted or when the error analysis routine returns control. 


Source: The SYNAD operand can be supplied in the DCB macro instruction or by the 
problem program. The problem program can also change the error routine address at 
any time. 
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Y 


DCBD—Provide Symbolic Reference to Data Control 


QSAM) 


Blocks (BDAM, BISAM, BPAM, BSAM, QISAM, and 


The DCBD macro instruction is used to generate a dummy control section that provides 
symbolic names for the fields in one or more data control blocks. The names and 
attributes of the fields appear as part of the description of each data control block in 
Appendix F of this publication. Attributes of the symbolically named fields in the dummy 
section are the same as the fields in the data control blocks, with the exception of fields 
containing 3-byte addresses. The symbolically named fields containing 3-byte addresses 
have length attributes of four and are aligned on fullword boundaries. 


The labels generated by the DCBD macro should not be defined within a user program. 
The macro labels are structured as DCBxxxxx where DCB are the first three characters 
and xxxxx are 1-5 alphameric characters. 


The name of the dummy control section generated by a DCBD macro instruction is 
IHADCB. The use of any of the symbolic names provided by the dummy section must be 
preceded by a USING instruction specifying IHADCB and a dummy section base 
register (which contains the address of the actual data control block). The DCBD macro 
instruction can only be issued once within any assembled module; however, the resulting 
symbolic names can be used for any number of data control blocks by changing the 
address in the dummy section base register. The DCBD macro instruction can be coded 
at any point in a control section; if coded at any point other than at the end of a control 
section; however, the control section must be resumed by coding a CSECT instruction. 


The DCBD macro instruction is written as follows: 


[DSORG=({GS | | 
[BS][,DA][,IS]L,LR][,PO][,PS][,QS]})] 


[,DEVD=([DA][,PC][,PRI[,PT][,RD][,TA] 
[,.MR][,OR])| 





DSORG=({GS | [BS][,DA][,IS][,LR][,PO][,PS][,QS]}) 
The DSORG operand specifies the types of data control blocks for which symbolic 
names are provided. If the DSORG operand is omitted, the DEVD operand is ignored, 
and symbolic names are provided only for the ‘foundation block’’ portion that is 
common to all data control blocks. One or more of the following pairs of characters 
can be specified (each pair of characters must be separated by a comma): 


BS 

Specifies a data control block for a sequential data set and basic access method. 
DA 

Specifies a data control block for a direct data set. 


IS | 
Specifies a data control block for an indexed sequential data set. 


LR . 
Specifies a dummy section for the logical record length field (DCBLRECL) only. 
PO. 

Specifies a data control block for a partitioned data set. 
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PS | | | 
Specifies a data control block for a sequential data set. PS includes both BS and 


QS. 
Qs 


Specifies a data control block for a sequential data set and queued access method. 


GS 
Specifies a data control block for graphics; this operand cannot be used in 
combination with any of the above. 


The DEVD operand specifies the types of devices on which the data set can reside. If 
the DEVD operand is omitted and a sequential data set is specified in the DSORG 
operand, symbolic names are provided for all of the device types listed below. One or 
more of the following pairs of characters can be specified; each pair of characters 
must be separated by a comma: 


DA 
Direct-access device 


PC 
Online punch 


PR 
Online printer 


PT 
Paper tape 


RD 
Online card reader or read punch feed 


TA 
Magnetic tape 


MR 
Magnetic character reader 


OR 
Optical character reader 
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ESETL—End Sequential Retrieval (QISAM) 


The ESETL macro instruction ends the sequential retrieval of data from an indexed 
sequential data set and causes the buffers associated with the specified data control block 
to be released. An ESETL macro instruction must separate SETL macro instructions 
issued for the same data control block. 


The ESETL macro instruction is written as follows: 


[symbol | | ESETL dcb address 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block opened for 
the indexed sequential data set being processed. 
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FEOV—Force End of Volume (BSAM and QSAM) 


The FEOV macro instruction causes the system to assume an end-of-volume condition, 
and causes automatic volume switching. Volume positioning for magnetic tape can be 
specified by the option operand. If no option is coded, the positioning specified in the 
OPEN macro instruction is used. Output labels are created as required and new input 
labels are verified. The standard exit routines are given control as specified in the data 
control block exit list. For BSAM, all input and output operations must be tested for 
completion before the FEOV macro instruction is issued. The end-of-data-set (EODAD) 
routine is given control if an input FEOV macro instruction is issued for the last volume 
of an input data set. FEOV is ignored if issued for a SYSIN or SYSOUT data set. 


The FEOV macro instruction is written as follows: 


[ symbol |] | FEOV acb address 
[REWIND | ,LEAVE] 


dcbh address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for an 
opened sequential data set. 


The following operands request optional services: 


REWIND 
Requests that the system position the tape at the load point regardless of the direction 
of processing. 


LEAVE 
Requests that the system position the tape at the logical end of the data set on that 
volume; this option causes the tape to be positioned at a point after the tapemark that 
follows the trailer labels. Note that multiple tape units must be available to achieve 
this positioning. If only one tape unit is available, its volume is rewound and unloaded. 


Note: If an FEOV macro is issued for a multivolume data set with spanned records that 
is being read using QSAM, errors may occur when the next GET macro is issued 
following an FEOV macro if the first segment on the new volume is not the first segment 
of a record. The errors include duplicate records, program checks in the user program, 
and invalid input from the variable spanned data set. 
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FIND—Establish the Beginning of a Data Set Member 


(BPAM) 


Completion Codes 


The FIND macro instruction causes the system to use the address of the first block of a 
specified partitioned data set member as the starting point for the next READ macro 
instruction for the same set. All previous input and output operations that specified the 
same data control block must have been tested for completion before the FIND macro 
instruction is issued. 


The FIND macro instruction is written as follows: 


[ symbol | | FIND dcb address 
»iname address ,.D | relative address list ,C} 


dcb address—RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the 
opened partitioned data set being processed. 


name address —-RX-Type Address, (2-12), or (0) 
The name address operand specifies the address of an 8-byte field that contains the 
data set member name. The name must start in the first byte and be padded on the 
right (if necessary) to complete the eight bytes. 


D 
Specifies that only a member name has been supplied, and the access method must 
search the directory of the data set indicated in the data control block to find the 
location of the member. 


relative address list —-RX-Type Address, (2-12), or (0) 
The relative address list operand specifies the address of the area that contains the 
relative address (TTRK) for the beginning of a data set member. The relative address 
can be a list entry completed by using a BLDL macro instruction for the data set 
being processed, or the relative address can be supplied by the problem program. 


Specifies that a relative address has been supplied, and no directory search is required. 
The relative address supplied is used directly by the access method for the next input 
operation. 


For relative address list, C, when the system returns control to the problem program, 


the low-order byte of register 15 contains the following return code; the three high-order 


bytes of register 15 are set to zero. 
relative address list, C 


00 — At all times. If the relative address is in error, execution of the next CHECK macro 
instruction causes control to be passed to the error analysis (SYNAD) routine. 
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For name address, D, when the system returns control to the problem program, the 
low-order byte of register 15 contains a return code and the low-order byte of register 0 
contains a reason code. The three high-order bytes of both registers are set to zero. 


name address, D 


Hexadecimal Codes 
Return (15) Reason (6) 

00 00 

04 00 

08 00 

08 04 
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Meaning 


Successful execution. 

Name not found. 

Permanent I/O error found during directory search. 
Insufficient virtual storage available. 


FREEBUF—Return a Buffer to a Pool (BDAM, 
BISAM, BPAM, and BSAM) 


The FREEBUF macro instruction causes the system to return a buffer to the buffer pool 


assigned to the specified data control block. The buffer must have been acquired using a 
GETBUF macro instruction. 


The FREEBUF macro instruction is written as follows: 


[ symbol |] | FREEBUF dcb address 
» register 


dcb address —-RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for an 
opened data set to which the buffer pool has been assigned. 

register —(2-12) 
The register operand specifies one of registers 2 through 12 that contains the address 
of the buffer being returned to the buffer pool. 
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FREEDBUF—Returm a Dynamically Obtained Buffer 
(BDAM and BISAM) 


The FREEDBUF macro instruction causes the system to return a buffer to the buffer 
pool assigned to the specified data control block. The buffer must have been acquired 
through dynamic buffering; that is, by coding ‘*S’ for the area address operand in the 
associated READ macro instruction. 


Note: A buffer acquired dynamically can also be released by a WRITE macro 
instruction; refer to the description of the WRITE macro instruction for BDAM or 
BISAM. 


The FREEDBUF macro instruction is written as follows: 









[symbol || FREEDBUF | decb address 
{K|D} 
,acb address 






decb address —RX-Type Address, (2-12), or (0) 
The decb address operand specifies the address of the data event control block 
(DECB) used or created by the READ macro instruction that acquired the buffer 
dynamically. 

K 
Specifies that BISAM is being used. 


D 
Specifies that BDAM is being used. 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the 
opened data set being processed. 
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FREEPOOL—Release a Buffer Pool (BDAM, BISAM, 
BPAM, BSAM, QISAM, and QSAM) 


The FREEPOOL macro instruction causes an area of storage, previously acquired for a 
buffer pool for a specified data control block, to be released. The area must have been 
acquired either automatically (except when dynamic buffer control is used) or by the 
execution of a GETPOOL macro instruction. For queued access methods, the 
FREEPOOL macro instruction must not be issued until after a CLOSE macro 
instruction has been issued for all the data control blocks using the buffer pool. For basic 
access methods, the FREEPOOL macro instruction can be issued as soon as the buffers 
are no longer required. A buffer pool should be released only once, regardless of the 
number of data control blocks sharing the buffer pool. | 


The FREEPOOL macro instruction is written as follows: 


[symbol] | FREEPOOL | dcb address — 





dcb address —_RX- -Type Address, (2-12), or (1) 
The dcb address operand specifies the address of a data control block to which the 
buffer pool has been assigned. 
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GET—Obtain Next Logical Record (QISAM) 


The GET macro instruction causes the system to retrieve the next record. Control is not 
returned to the problem program until the record is available. 


The GET macro instruction is written as follows: 


[ symbol |] | GET dcb address 
[,area address | 


dcb address—-RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the 
opened input data set being retrieved. 


area address —RX-Type Address, (2-12), or (0) 
The area address operand specifies the storage address into which the system is to 
move the record (move mode only). Either the move or locate mode can be used with 
QISAM, but they must not be mixed within the specified data control block. The 
following describes operations for move and locate modes: 


Locate Mode: If the locate mode has been specified in the data control block, the area 
address operand must be omitted. The system returns the address of the buffer 
segment containing the record in register 1. 


Move Mode: If the move mode has been specified in the data control block, the area 
address operand must specify the address in the problem program into which the 
system will move the record. If the area address operand is omitted, the system 
assumes that register 0 contains the area address. When control is returned to the 
problem program, register 0 contains the area address, and register 1 contains the 
address of the data control block. 


Notes: 


1. The end-of-data-set (EODAD) routine is given control if the end of the data set is 
reached; the data set may be closed if processing is completed, or an ESETL macro 
must be issued before a SETL macro to continue further input processing. 


2. The error analysis (SYNAD) routine is given control if the input operation could not 
be completed successfully. The contents of the general registers when control is given 
to the SYNAD routine are described in Appendix A. 


3. When the key of an unblocked fixed-length record is retrieved with the data, the 
address of the key is returned as follows (see the SETL macro instruction): 


Locate Mode: The address of the Key is returned in register 0. 
Move Mode: The key appears in front of the record in your buffer area. 


4. If a GET macro instruction is issued for a data set and the previous request issued for 
the same data set was an OPEN, ESETL, or unsuccessful SETL (no record found), a 
SETL B (key and data) is invoked automatically, and the first record in the data set is 
returned. 
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GET—Obtain Next Logical Record (QSAM) 


The GET macro instruction causes the system to retrieve the next record. Various modes 
are available and are specified in the DCB macro instruction. In the locate mode, the 
GET macro instruction locates the next sequential record or record segment to be 
processed. The system returns the address of the record in register 1 and places the 
length of the record or segment in the logical-record-length (DCBLRECL) field of the 
data control block. The user can process the record within the input buffer or move the 
record to a work area. 


In the move mode, the GET macro instruction moves the next sequential record to the 
user’s work area. This work area must be big enough to contain the largest logical record 
of the data set and its record-descriptor word (variable-length records). The system 
returns the address of the work area in register 1. (This feature provides compatibility 
with the substitute mode GET.) The record length is placed in the DCBLRECL field. 
The move mode can be used only with simple buffering. 


In the data mode, which is available only for variable-length spanned records, the GET 
macro instruction moves only the data portion of the next sequential record to the user’s 
work area. The TYPE=P operand cannot be used with data mode. 


In the substitute mode, the GET macro instruction transfers ownership of the next 
sequential record in a data set from the system to the user. In return, the ownership of a 
work area is transferred from the user to the system for future use as an input buffer. 
There is no movement of data. The address of an input buffer containing the record is 
returned to the user in register 1 after the instruction is executed. The system returns the 
record length in the DCBLRECL field. For undefined-length records, the DCBLRECL 
field is equal to the BLKSIZE field for chained scheduling. The substitute mode can be 
used only with exchange buffering and cannot be used with variable-length records. The 
TYPE=P operand cannot be used with substitute mode. 


If the ASCII translation routines are included when the operating system is generated, 
translation can be requested by coding LABEL=(,AL) or (,AUL) in the DD statement, 
or it can be requested by coding OPTCD=Q in the DCB macro instruction or DCB 
subparameter of the DD statement. When translation is requested, all QSAM records 
whose record format (RECFM operand) is F, FB, D, DB, or U are automatically 
translated from ASCII code to EBCDIC code as soon as the input buffer is full. For 
translation to occur correctly, all input data must be in ASCII code. 


The GET macro instruction is written as follows: 


[ symbol | | GET dcb address | pdab address 
[,area address | 
[,TYPE=P] 





dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the 
opened input data set being retrieved. 


pdab address —RX-Type Address, (2-12), or (1) 
The pdab address operand specifies the address of the parallel data access block for 
the opened input data sets from which a record is to be retrieved. When pdab address 
is used, TYPE=P must be coded. 


Macro Instruction Descriptions: GET—QSAM 145 


area address —-RX-Type Address, (2-12), or (0) 
The area address operand specifies the address of an area into which the system is to 
move the record (move or data mode), or it specifies the address of an area to be 
exchanged for the buffer containing the record (substitute mode). The move, locate, 
data, or substitute mode can be used with QSAM, but they must not be mixed within 
the specified data control block. If the area address operand is omitted in the move, 
data, or substitute mode, the system assumes that register O contains the area address. 
The following describes the operation of the four modes: 


Locate Mode: If the locate mode has been specified in the data control block, the area 
address operand must be omitted. The system returns the address of the beginning 
buffer segment containing the record in register 1. If the data set is open for 
RDBACK, register 1 will point to the end of the buffer segment rather than the 
beginning. 


When retrieving variable-length spanned records, the records are obtained one 
segment at a time. The problem program must retrieve additional segments by issuing 
subsequent GET macro instructions, except when a logical record interface is 
requested (by specifying BFTEK=A in the DCB macro instruction or by issuing a 
BUILDRCD macro instruction.) In this case, the control program retrieves all record 
segments and assembles the segments into a complete logical record. The system 
returns the address of this record area in register 1. To process a record when the 
logical record length is greater than 32,756 bytes, LRECL=X must be specified in the 
data control block, and the problem program must assemble the segments into a 
complete logical record. 


Move Mode: If the move mode has been specified in the data control block, the area 
address operand specifies the beginning address of an area in the problem program 
into which the system will move the record. If the data set is open for RDBACK, the 
area address operand specifies the ending address of an area in the problem program. 


For variable-length spanned records, the system constructs the record-descriptor word 
in the first four bytes of the area and assembles one or more segments into the data 
portion of the logical record; the segment descriptor words are removed. 


Data Mode: If the data mode has been specified in the data control block (data mode 
can be specified for variable-length spanned records only), the area address operand 
specifies the address of the area in the problem program into which the system will 
move the data portion of the logical record; a record-descriptor word is not 
constructed when data mode is used. The TYPE=P operand cannot be used with data 
mode. 


Substitute Mode: If the substitute mode is specified in the data control block, the area 
address operand specifies the address of an area in the problem program that will be 
exchanged for the buffer containing the record. The system returns the address of the 
buffer containing the record in register 1. The TYPE=P operand cannot be used with 
substitute mode. 


Note: If spanned records extend across volumes, errors may occur when using the 
GET macro if a volume which begins with a middle or last record segment is mounted 
first, or if an FEOV macro is issued followed by a GET macro. QSAM cannot begin 
reading from the middle of the record. (This applies to move mode, data mode, and 
locate mode if logical record interface is specified.) 
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TYPE=P—Coded as shown 
The TYPE=P and pdab address operands are used to retrieve a record from a queue 
of input data sets that have been opened. The open and close routines add and delete 
DCB addresses in the queue. The DCB from which a record is retrieved can be 
located from information in the PDAB. For this purpose, the formatting macro, 
PDABD, should be used. 


GET Routine Exits 


The end-of-data-set (EODAD) routine is given control if the end of the data set is 
reached; the data set must be closed. Issuing a GET macro instruction in the EODAD 
| routine results in abnormal termination of the task. 


The error analysis (SYNAD) routine is given control if the input operation could not be 
completed successfully. The contents of the general registers when control is given to the 
SYNAD routine are described in Appendix A. 
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GETBUF—Obtain a Buffer (BDAM, BISAM, BPAM, 
and BSAM) 


The GETBUF macro instruction causes the control program to obtain a buffer from the 
buffer pool assigned to the specified data control block and to return the address of the 
buffer in a designated register. The BUFCB field of the data control block must contain 
the address of the buffer pool control block when the GETBUF macro instruction is 
issued. The system returns control to the instruction following the GETBUF macro 
instruction. The buffer obtained must be returned to the buffer pool using a FREEBUF 
macro instruction. 


i The GETBUF macro instruction is written as follows: 


[ symbol | | GETBUF dcb address 
register, Se ee 


dcb address —-RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block that contains 
the buffer pool control block address. 


register —(2-12) 
The register operand specifies one of the registers 2 through 12 in which the system is 


to place the address of the buffer obtained from the buffer pool. If no buffer is 
available, the contents of the designated register are set to zero. 
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GETPOOL—Build a Buffer Pool (BDAM, BISAM, 
BPAM, BSAM, QISAM, and QSAM) 


The GETPOOL macro instruction causes a buffer pool to be constructed in a storage 
area acquired by the system. The system places the address of the buffer pool control 
block in the BUFCB field of the data control block. The GETPOOL macro instruction 
must be issued either before an OPEN macro instruction is issued or during the data 
control block exit routine for the specified data control block. 


The GETPOOL macro instruction is written as follows: 


[symbol|]| GETPOOL | dcb address 
»tnumber of buffers, buffer length | (0)} 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block to which the 
buffer pool is assigned. Only one buffer pool can be assigned to a data control block. 


number of buffers —symbol, decimal digit, absexp, or (2-12) 
The number-of-buffers operand specifies the number of buffers in the buffer pool up 
to a maximum of 255. 


buffer length—symbol, decimal digit, absexp, or (2-12) 
The buffer length operand specifies the length, in bytes, or each buffer in the buffer 
pool. The value specified for the buffer length must be a doubleword multiple; 
otherwise the system rounds the value specified to the next higher doubleword 
multiple. The maximum length that can be specified is 32,760 bytes. For QSAM, the 
buffer length must be at least as large as the value specified in the block size 
(DCBBLKSIJ) field in the data control block. 


(0)—-Coded as shown 
The number of buffers and buffer length can be specified in general register 0. If (0) 
is coded, register 0 must contain the binary values for the number of buffers and 
buffer length as shown in the following illustration: 


Register 0 


Number of Buffers 






Buffer Length 





Bits: 
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The following illustration shows the format of the buffer pool. The buffer pool and the 
associated storage area are released by issuing a FREEPOOL macro instruction after 


issuing a CLOSE macro instruction for the data set indicated in the specified data control 
block. 


Area 
Address 





BUFNO BUFL 
Address of First 
Available of Each Buffer Buffer 
Buffer Buffers Buffer 


Buffer Pool Control ea ie Buffer ee ee Length 
(8 bytes) 







FN or Oral (14 0 Gee Ea DRE ere Eero roe 


Area Length= (Buffer Length) x (Number of Buffers) +8 


152 OS/VS Data Management Macro Instructions 


NOTE—Provide Relative Position (BPAM and 
BSAM—tTape and Direct Access Only) 


The NOTE macro instruction causes the system to return the relative position of the last 
block read from or written into a data set. All input and output operations using the same 
data control block must be tested for completion before the NOTE macro instruction is 
issued. 


The capability of using the NOTE macro instruction is automatically provided when a 
partitioned data set is used (DSORG=PO or POU), but when a sequential data set 
(BSAM) is used, the use of NOTE/POINT macro instructions must be indicated in the 
MACREF operand of the DCB macro instruction. The relative position, in terms of the 
current volume, is returned in register 1 as follows: 


Magnetic Tape: The block number is in binary, right-adjusted in register 1 with 
high-order bits set to zero. Do not use a NOTE macro instruction for tapes without 
standard labels when: 


« The data set is opened for RDBACK (specified in the OPEN macro instruction) or 
¢« The DISP parameter of the DD statement for the data set specifies DISP=MOD. 
Direct-Access Device: TTRz format, where: 

TT is a 2-byte relative track number. 

Risa 1-byte block (record) number on the track indicated by TT. 

z isa byte set to zero. 


For VS1 SYSIN data sets, register 1 returns a 4-byte relative block address for the last 
record read. The NOTE macro instruction cannot be used for VS2 SYSIN data sets, or 
for VS1 or VS2 SYSOUT data sets. 


Note: When a direct-access device is being used, the amount of remaining space on the 
track is returned in register 0 if a NOTE macro instruction follows a WRITE macro 

| instruction; if a NOTE macro instruction follows a READ or POINT macro instruction, 
the track capacity of the direct-access device is returned in register 0. 


The NOTE macro instruction is written as follows: 


[ symbol | | NOTE dcb address 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block opened for 
the partitioned or sequential data set being processed. 
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OPEN—Logically Connect a Data Set (BDAM, 
BISAM, BPAM, BSAM, QISAM, and QSAM) 


The OPEN macro instruction causes the specified data control block(s) to be completed 
and the data set(s) identified in the data control block(s) to be prepared for processing. 
Input labels are analyzed and output labels are created. Control is given to exit routines 
as specified in the data control block exit list. The processing method (option 1) is 
designated to provide correct volume positioning for the data set and define the 
processing mode (INPUT, OUTPUT, etc.) for the data set(s). Final volume positioning 
(when volume switching occurs) can be specified (option 2) to override the positioning 
implied by the DD statement DISP parameter. Option 2 applies only to volumes in a 
multivolume data set other than the last volume. Any number of data control block 
addresses and associated options may be specified in the OPEN macro instruction. 


If associated data sets for a 3525 card punch are being opened, all associated data sets 
must be open before an I/O operation is initiated for any of the data sets. Fora 
description of associated data sets, refer to OS/VS Data Management Services Guide. 


-& 
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The standard form of the OPEN macro instruction is written as follows (the list and 
execute forms are shown following the description of the standard form): 


[ symbol |] | OPEN (dcb address ,|( options )], ...) 


dcb address —A-Type Address or (2-12) 
The dcb address operand(s) specifies the address of the data control block(s) for the 
data set(s) to be prepared for processing. 


options 
The options operands shown in the following illustration indicate the volume 
positioning available based on the device type and access method being used. If option 
1 is omitted, INPUT is assumed. If option 2 is omitted, DISP is assumed. Option 1 
must be coded if option 2 is coded. Option 2 is ignored for SYSIN and SYSOUT data 
sets. Options 1 and 2 are ignored for BISAM and QISAM (in the scan mode), and the 
data control block indicates the operation. OUTPUT or OUTIN must be specified 
when creating a data set. 
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ACCESS 
METHOD 


QSAM 


BSAM 


QISAM 
(Load Mode) 


BPAM, 
BDAM 


Magnetic tape 


Option 1 


[INPUT ] 
[OUTPUT ] 
[RDBACK] 


[INPUT  ] 
[OUTPUT ] 
[INOUT ] 
[OUTIN ] 
[RDBACK ] 


DEVICE TYPE 


Direct access Other Types 
Option 2 Option I Option 2 Option 1 Option 2 
[.REREAD | [INPUT ] [.REREAD ] [INPUT ] — 
[LEAVE ] [OUTPUT] [LEAVE ] [OUTPUT ] 
[,DISP ] [UPDAT ] [,DISP ] 
[,.REREAD ] [INPUT ] [.REREAD ] IINPUT |] —_ 
[LEAVE ] [OUTPUT] [LEAVE ] [OUTPUT] 
[,DISP ] [INOUT J [,DISP ] 
[OUTIN ] 
[UPDAT ] 
= [OUTPUT] aad a — 
— [INPUT ] — at — 
[OUTPUT] 
[UPDAT ] 


The following describes the options shown in the preceding illustration. All option 
operands are coded as shown. 


Option 1 
INPUT 
INOUT 


OUTPUT 
OUTIN 


RDBACK 
UPDAT 


Option 2 
LEAVE 


REREAD 


DISP 


Meaning 
Input data set. 


The data set is first used for input and, without reopening, it is used as 
an output data set. The data set is processed as INPUT for a SYSIN 
data set or if LABEL=(,,,IN) is specified in the DD statement. 


Output data set (for BDAM, OUTPUT is equivalent to UPDAT). 


The data set is first used for output and, without reopening, it is used as 
an input data set. The data set is processed as OUTPUT for a SYSOUT 
data set or if LABEL=(,,,OUT) is specified in the DD statement. 


Input data set, positioned to read backward. 


Data set to be updated in place or, for BDAM, blocks are to be updated 
or added. 


Meaning 


Positions the current tape volume to the logical end of the data set when 
volume switching occurs. If processing was forward, the volume is 
positioned to the end of the data set; if processing was backwards 
(RDBACK), the volume is positioned to the beginning of the data set. 


Positions the current tape volume to reprocess the data set when volume 
switching occurs. If processing was forward, the volume is positioned to 
the beginning of the data set; if processing was backwards (RDBACK), 
the volume is positioned to the end of the data set. 


Specifies that a tape volume is to be disposed of in the manner implied 
by the DD statement associated with the data set. Direct-access volume 
positioning and disposition are not affected by this parameter of the 
OPEN macro instruction. There are several dispositions that can be 
specified in the DISP parameter of the DD statement; DISP can be 
PASS, DELETE, KEEP, CATLG, or UNCATLG. This option has 
significance at the time an end-of-volume condition is encountered only 
when DISP is PASS. The end-of-volume condition may result from the 
issuance of an FEOV macro instruction or may be the result of reaching 
the end of a volume. 
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If DISP is PASS in the DD statement, the tape will be spaced forward to 
the end of the data set on the current volume. 


VS1 Systems: If any DISP option is coded in the DD statement the 
current volume will be positioned as follows: 


DISP Parameter Action 


PASS Forward space to the end of the data set on the 
| current volume 

DELETE Rewind the current volume 

KEEP, CATLG, or UNCATLG —__ Rewind and unload the current volume 


VS2 Systems: If any DISP option is coded in the DD statement (except 
when DISP is PASS), the resultant action at the time an end-of-volume 
condition arises depends on (1) how many tape units are allocated to 
the data set and (2) how many volumes are specified for the data set in 
the DD statement. This is determined by the UNIT and VOLUME 
parameters of the DD statement associated with the data set. If the 
number of volumes is greater than the number of units allocated, the 
current volume will be rewound and unloaded. If the number of volumes 
is less than or equal to the number of units, the current volume is merely 
rewound. 


Note: When the DELETE option is specified, the system waits for the completion of the 
rewind operation before it continues processing subsequent reels of tape. 


The LEAVE and REREAD options are meaningless except for magnetic tape and 
CLOSE TYPE=T. Any other options specified for CLOSE TYPE=T besides LEAVE 
and REREAD will be treated as LEAVE during execution. 


After the OPEN macro instruction has been executed, bit 3 of the DCBOFLGS field in 
the data control block is set to 1 if the data control block has been opened successfully, 
but is set to 0 if the data control block has not been opened successfully. 


The following errors cause the results indicated: 
Error Result 


Attempting to open a data control No action. 
block that is already open. 


Attempting to open a data control Unpredictable. 
block when the dcb address 

operand does not specify the 

address of a data control block. 


Attempting to open a DCB for a Unpredictable (VS1 only). 
printer with the UCS feature and 

an error occurred when attempting Task abnormally terminated 
to block or unblock data checks (VS2 only). 

(specified by the presence or absence 

of OPTCD=U in the DCB macro). 


Attempting to open a data control A “DD STATEMENT MISSING” message 
block when a corresponding DD is issued. An attempt to use the data 
statement has not been provided. set causes unpredictable results. 
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The last of these errors can be detected by testing bit 3 of the DCBOFLGS field in the 
data control block. Bit 3 is set to 0 in the case of an error and can be tested by the 
sequence: 


TM DCBOFLGS,X‘10’ 
BZ ERRORRTN (Branch to user's error routine) 
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OPEN—List Form 


The list form of the OPEN macro instruction is used to construct a data management 
parameter list. Any number of operands (data control block addresses and associated 
options) can be specified. 


The list consists of a one-word entry for each DCB in the parameter list; the high-order 
byte is used for the options and the three low-order bytes are used for the DCB address. 
The end of the list is indicated by a one in the high-order bit of the last entry’s option 
byte. The length of a list generated by a list form instruction must be equal to the 
maximum length list required by any execute form instruction that refers to the same list. 
A maximum length list can be constructed by one of two methods: 


¢ Code a list-form instruction with the maximum number of parameters that are 
required by an execute form instruction that refers to the list. 


e Code a maximum length list by using commas in a list-form instruction to acquire a list 
of the appropriate size. For example, coding OPEN (,,,,,,,,) MF=L would provide a 
list of five fullwords (five dcb addresses and five options). 


Entries at the end of the list that are not referenced by the execute-form instruction are 
assumed to have been filled in when the list was constructed or by a previous 
execute-form instruction. Before using the execute-form instruction, you may shorten the 
list by placing a one in the high-order bit of the last DCB entry to be processed. 


A zeroed work area on a fullword boundary is equivalent to OPEN 
(,INPUT,DISP),...),MF=L and can be used in place of a list-form instruction. The 
high-order bit of the last DCB entry must contain a one before this list can be used with 
the execute-form instruction. 


A parameter list constructed by an OPEN, list form, macro instruction can be referred to 
_ by either an OPEN or CLOSE execute form instruction. 


The description of the standard form of the OPEN macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are completely optional and those required in at least one of 
the pair of list and execute forms. The format description below indicates the optional 
and required operands in the list form only. 


The list form of the OPEN macro instruction is written as follows: 


[ symbol | | OPEN ({dcb address |,|( options )|, ...) 
JMF=L 


or address —A-Type Address 


MF=L—Coded as shown 
The MF=L operand specifies that the OPEN macro instruction is used to create a 
data management parameter list that is referenced by an execute form instruction. 
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OPEN—Execute Form 


A remote data management parameter list is used in, and can be modified by, the execute 
form of the OPEN macro instruction. The parameter list can be generated by the list 
form of either an OPEN or CLOSE macro instruction. 


The description of the standard form of the OPEN macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are totally optional and those required in at least one of the 
pair of list and execute forms. The format description below indicates the optional and 
required operands in the execute form only. 


The execute form of the OPEN macro instruction is written as follows: 


[symbol | | OPEN 





dcb address —RX-Type Address or (2-12) 


MF=(E,{ data management list address | (1)} 
This operand specifies that the execute form of the OPEN macro instruction is used, 
and an existing data management parameter list (created by a list-form instruction) is 
used. The MF= operand is coded as follows: 


E—Coded as shown 
data management list address —RX-Type, (2-12), (1) 
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PDAB—cConstruct a Parallel Data Access Block 
(QSAM) 


The PDAB macro instruction is used in conjunction with the GET (TYPE=P) macro 
instruction. It defines an area in the problem program where the Open and Close 
routines build and maintain a queue of DCB address for use by the Get routine. 


The parallel data access block is constructed during the assembly of the problem 
program. The MAXDCB operand must be coded in the PDAB macro instruction because 
it cannot be supplied from any other source. | 


Certain data set characteristics prevent a DCB address from being available on the 
queue—see the description of QSAM parallel input processing in OS/VS Data 
Management Services Guide. 


The PDAB macro instruction is written as follows: 


[symbol | | PDAB MAXDCB=dcb number 


MAXDCB=absexp (maximum value is 32,767) 
Specifies the maximum number of DCBs that you require in the queue for a GET 
request. 


Note: The number of bytes required for PDAB is equal to 24+87 where n is the 
value of the keyword, MAXDCB. 
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PDABD—Provide Symbolic Reference to a Parallel Data 
Access Block (QSAM) 


The PDABD macro instruction is used to generate a dummy control section that provides 
symbolic names for the fields in one or more parallel data access blocks. The names, 
attributes, and descriptions of the fields appear in Appendix H. 


The name of the dummy control section generated by a PDABD macro instruction is 
IHAPDAB. The use of any of the symbolic names provided by the dummy section 
should be preceded by a USING instruction specifying IHAPDAB and a dummy section 
base register containing the address of the actual parallel data access block. The PDABD 
macro instruction should only be used once within any assembled module; however, the 
resulting symbolic names can be used for any number of parallel data access blocks by 
changing the address in the dummy section base register. The PDABD macro instruction 
can be coded at any point in a control section. If coded at any point other than at the end 
of a control section, the control section must be resumed by coding a CSECT instruction. 


The PDABD macro instruction is written as follows: 


a ee 
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POINT—Position to a Relative Block (BPAM and 
BSAM-—tTape and Direct Access Only) 


The POINT macro instruction causes the system to start processing the next READ or 
WRITE operation at the specified block in the data set on the current volume. All input 
and output operations using the same data control block must have been tested for 
completion before the POINT macro instruction is issued. When processing a data set 
that has been opened for UPDAT, the POINT macro instruction must be followed by a 
READ macro instruction. When processing an output data set, the POINT macro 
instruction must be followed by a WRITE macro instruction prior to closing the data set, 
unless a CLOSE macro instruction (with TYPE=T specified) was issued prior to the 
POINT macro instruction. Issuing a POINT macro instruction for a system output data 
set on magnetic tape results in an effective NOP instruction (VS1 only). 


The POINT macro instruction is written as follows: 


[ symbol | | POINT dcb address 
» block address 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the 
opened data set that is to be positioned. 


block address —RX-Type Address, (2-12), or (0) 
The block address operand specifies the address of a fullword on a fullword boundary 
containing the relative address of the block in the data set that is to be processed next. 
The relative address is specified as follows: 


Magnetic Tape: The block number is in binary and is right-adjusted in the fullword 
with the high-order bits set to zero; add one if reading tape backward. Do not use the 
POINT macro instruction for tapes without standard labels when: 


e« The data set is opened for RDBACK or 
e The DD statement for the data set specifies DISP=MOD. 


If OPTCD=H is indicated in the data control block, the POINT macro instruction can 
be used to perform record positioning on DOS tapes that contain embedded 
checkpoint records. Any embedded checkpoint records that are encountered during 
the record positioning are bypassed and are not counted as blocks spaced over. 
OPTCD=H must be specified in a job control language DD statement. Do not use the 
POINT macro instruction to backspace DOS 7-track tapes that are written in data 
convert mode and that contain embedded checkpoint records. 


Note: When an end-of-data condition is encountered on magnetic tape, you must not 
issue the POINT macro instruction unless you have first repositioned the tape for 
processing within your data set; otherwise, the POINT operation will be unsuccessful. 
(Issuing CLOSE TYPE=T is an easy method to accomplish repositioning in your 
EODAD routine.) 


Direct-Access Device: The fullword specified in the block address operand contains 
the relative track address (in the form TTRz), where: 


TT is a 2-byte relative track number. 
R_ isa 1-byte block (record) number on the track indicated by TT. 


Z isa byte set to zero; it may also be set to 1 to retrieve the block following the 
TTR block. 
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Note: The first block of a magnetic tape data set is always specified by the 
hexadecimal value 00000001. The first block of a direct-access device data set can be 
specified by either hexadecimal 00000001 or 00000100 (see the previous description 
of TTRz). 


The fullword specified in the block address operand contains the relative block address 
for a VS1 SYSIN data set. The 4-byte relative block address must have been returned in 
register 1 from a previous NOTE macro instruction and it cannot be altered. POINT 
cannot be used for VS2 SYSIN data sets or for VS1 or VS2 SYSOUT data sets. 


If the volume cannot be positioned correctly or if the block identification is not of the 
correct format, the error analysis (SYNAD) routine is given control when the next 
CHECK macro instruction is executed. 
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PRTOV—tTest for Printer Carriage Overflow (BSAM 
and QSAM—Online Printer and 3525 Card Punch, 
Print Feature) 


The PRTOV macro instruction is used to control the page format for an online printer 
when carriage control characters are not being used or to supplement the carriage control 
characters that are being used. 


The PRTOV macro instruction causes the system to test for an overflow condition on the 

specified channel (either channel 9 or channel 12) of the printer carriage control, and 

either skip the printer carriage to the line corresponding to channel 1, or transfer control 

to the exit address, if one is specified. Overflow is detected after printing the line that 

follows the line corresponding to channel 9 or channel 12. The PRTOV macro should be 
issued each time you want the system to test for an overflow condition. 


When the PRTOV macro instruction is used with a 3525 card punch, print feature, 
channel 9 or 12 can be tested. If an overflow condition occurs, control is passed to the 
overflow exit routine if the overflow exit address is coded, or a skip to channel 1 (first 
print-line of the next card) occurs. 


When requesting overprinting (for example, to underscore a line), the PRTOV macro 
instruction is issued before the first PUT or WRITE macro instruction only. The PRTOV 
macro instruction should be issued only when the device type is an online printer. 
PRTOV cannot be used to request overprinting on the 3525. 


The PRTOV macro instruction is written as follows: 


[ symbol | PRTOV dcb address 


19 | 12} 
[,overflow exit address | 





dcb address —RX-Type Address or (2-12) | 
The dcb address operand specifies the address of the data control block opened for 
output to an online printer or 3525 card punch with a print feature. 


9—Coded as shown 

12—-Coded as shown 
These operands specify which channel is to be tested by the PRTOV macro 
instruction. For an online printer, 9 and 12 correspond to carriage control channels 9 
and 12. For the 3525 card punch, 9 corresponds to print line number 17, and 12 
corresponds to print line number 23. More detail about the card print-line format is 
included in OS and OS/VS Programming Support for the IBM 3505 Card 
Reader and IBM 3525 Card Punch. 


overflow exit address —-RX-Type Address or (2-12) 
The overflow exit address operand specifies the address of the user-supplied routine 
to be given control when an overflow condition is detected on the specified channel. If 
this operand is omitted, the printer carriage skips to the first line of the next page or 
the 3525 skips to the first line of the next card before executing the next PUT or 
WRITE macro instruction. 
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When the overflow exit routine is given control, the contents of the registers are as 
follows: 


Register Contents 


0 and 1 The contents are destroyed. 


2-13 The same contents as before the macro instruction was 
executed. 

14 Return address. 

15 Overflow exit routine address. 
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PUT—Write Next Logical Record (QISAM) 


The PUT macro instruction causes the system to write a record into an indexed 
sequential data set. If the move mode is used, the PUT macro instruction moves a logical 
record into an output buffer from which it is written. If the locate mode is specified, the 
address of the next available output buffer segment is available in register 1 after the 
PUT macro instruction is executed. The logical record can then be constructed in the 
buffer for output as the next record. The records are blocked by the system (if specified 
in the data control block) before being placed in the data set. The system uses the length 
specified in the record length (DCBLRECL) field of the data control block as the length 
of the record currently being written. When constructing blocked variable-length records 
in the locate mode, the problem program may either specify the maximum record length 
once in the DCBLRECL field of the data control block or provide the actual record 
length in the DCBLRECL field before issuing each PUT macro instruction. Use of the 
maximum record length may result in more but shorter blocks, since the system uses this 
length when it tests to see if the next record can be contained in the current block. 


The PUT macro instruction is used to create or extend an indexed sequential data set. To 
extend the data set, the key of any added record must be higher than the highest key 
existing in the data set, and the disposition parameter of the DD card must be specified 
as DISP=MOD. The new records are placed in the prime data space, starting in the first 
available space, until the original space allocation is exhausted. 


To create a data set using previously allocated space, the disposition parameter of the 
DD card must specify DISP=OLD. 


The PUT macro instruction is written as follows: 


[ symbol | | PUT dcb address 
[,area address | 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the 
opened ISAM data set. 


area address—RX-Type Address, (2-12), or (0) 
The area address operand specifies the address of the area that contains the record to 
be written (move mode only). Either move or locate mode can be used with QISAM, 
but they must not be mixed within the specified data control block. The following 
describes operations for locate and move modes: 


Locate Mode: If the locate mode is specified in the data control block, the area 
address operand must be omitted. The system returns the address of the next available 
buffer in register 1; this is the buffer into which the next record is placed. The record 
is not written until another PUT macro instruction is issued for the same data control 
block. The last record is written when a CLOSE macro instruction is issued to close 
the data set. 


Move Mode: If the move mode has been specified in the data control block, the area 
address operand must specify the address in the problem program that contains the 
record to be written. The system moves the record from the area to an output buffer 
before control is returned. If the area address operand is omitted, the system assumes 
that register zero contains the area address. 
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PUT Routine Exit 


The error analysis (SYNAD) routine is given control if the output operation could not be 
completed satisfactorily. The contents of the registers when the error analysis routine is 
given control are described in Appendix A. 
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PUT—Write Next Logical Record (QSAM) 


The PUT macro instruction causes the system to write a record in a sequential data set. 
Various modes are available and are specified in the DCB macro instruction. In the 
locate mode, the address of an area within an output buffer is returned in register 1 after 
the macro instruction is executed. The user should subsequently construct, at this 
address, the next sequential record or record segment. The move mode of the PUT 
macro instruction causes a logical record to be moved into an output buffer. In the data 
mode, which is available only for variable-length spanned records, the PUT macro 
instruction moves only the data portion of the record into one or more output buffers. 
When the substitute mode is specified, the macro transfers ownership of a work area 
containing a record to the control program. In return, the ownership of a buffer segment 
is transferred to the user, for use as a work area. There is no movement of data in 
storage. | 


The records are blocked by the control program (as specified in the data control block) 
before being placed in the data set. For undefined-length records, the DCBLRECL field 
determines the length of the record that is subsequently written. For variable-length 
records, the DCBLRECL field is used to locate a buffer segment of sufficient size 
(locate mode), but the length of the record actually constructed is verified before the 
record is written (the output block can be filled to the maximum if, before issuing the 
PUT macro, DCBLRECL is set equal to the record length). For variable-length spanned 
records, the system segments the record according to the record length, buffer length, 
and amount of unused space remaining in the output buffer. The smallest segment 
created will be 5 bytes, 4 for the segment descriptor word plus one byte of data. 


If the ASCII translation routines are included when the operating system is generated, 
translation can be requested by coding LABEL=(,AL) or (,AUL) in the DD statement, 
or it can be requested by coding OPTCD=Q in the DCB macro instruction or DCB 
subparameter of the DD statement. When translation is requested, all QSAM records 
whose record format (RECFM operand) is F, FB, D, DB, or U are automatically 
translated from EBCDIC code to ASCII code. For translation to occur correctly, all 
output data must be in EBCDIC code; any EBCDIC character that cannot be translated 
into an ASCII character is replaced by a substitute character. 


The PUT macro instruction is written as follows: 


[symbol | | PUT dcb address 
[,area address | 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the data 
set opened for output. 


area address —RX-Type Address, (2-12), or (0) 
The area address operand specifies the address of an area that contains the record to 
be written (move or data mode), or it specifies the address of an area to be exchanged 
for a buffer (substitute mode). The move, locate, data, or substitute mode can be used 
with QSAM, but they must not be mixed within the specified data control block. If the 
area address operand is omitted in the move, data, or substitute mode, the system 
assumes that register zero contains the area address. The following describes the 
operation of the four modes: 





Locate Mode: If the locate mode is specified, the area address operand must be 
omitted. The system returns the address of the next available buffer in register 1; this 
is the buffer into which the next record is placed. 
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When variable-length spanned records are used and a record area has been provided 
for a logical record interface (BFTEK=A has been specified in the data control block 
or a BUILDRCD macro instruction has been issued), the address returned in register 
1 points to an area large enough to contain the maximum record size (up to 32,756 
bytes). The system segments the record and writes all segments, providing proper 
control codes for each segment. If, for variable-length spanned records, an area has 
not been provided, the actual length remaining in the buffer will be returned in 
register 0. In this case, it is the user’s responsibility to segment the records and process 
them in terms of record segments. The record or segment is not written until another 
PUT macro instruction is issued for the same data control block. The last record is 
written when the CLOSE macro instruction is issued. 


When a PUT macro instruction is used in the locate mode, the address of the buffer 
for the first record or segment is obtained by issuing a PUT macro instruction; QSAM 
returns the address of the buffer, but the record is not written until the next PUT 
macro instruction is issued. 


Move Mode: If the move mode has been specified in the data control block, the area 
address operand specifies the address of the area that contains the record to be 
written. The system moves the record to an output buffer before control is returned. 
The address of the output buffer is returned in register 1 (this action provides 
compatibility with substitute mode operations, and makes it possible for the problem 
program to be used in instances where substitute mode is requested but cannot be 
supported by the system). 


Data Mode: If the data mode is specified in the data control block (data mode can be 
specified for variable-length spanned records only), the area address operand 
specifies the address of an area in the problem program that contains the data portion 
of the record to be written. The system moves the data portion of the record to an 
output buffer before control is returned. The user must place the total data length in 
the DCBPRECL (not DCBLRECL) field of the data control block before the PUT 
macro instruction is issued. 


Substitute Mode: If the substitute mode is specified in the data control block, the area 
address operand specifies the address of an area in the problem program that contains 
the next record to be written. The area is exchanged for an empty buffer. The address 
of the empty buffer is returned in register 1. 


PUT Routine Exit 


The error analysis (SYNAD) routine is given control if an output operation could not be 
completed satisfactorily. If the output operation could not be completed satisfactorily, 
the error analysis (SYNAD) routine is given control after the next PUT instruction is 
issued. The contents of the registers when the error analysis routine is given control are 
described in Appendix A. 
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PUTX—Write a Record from an Existing Data Set 
(QISAM and QSAM) 


The PUTX macro instruction causes the control program to return an updated record to 
a data set (QISAM and QSAM) or to write a record from an input data set into an 
output data set (QSAM only). There are two modes of the PUTX macro instruction. The 
output mode (QSAM only) allows writing a record from an input data set on a different 
output data set. The output data set may specify the spanning of variable-length records, 
but the input data set must not contain spanned records. 


The update mode returns an updated record to the data set from which it was read. The 
logical records are blocked by the control program, as specified in the data control block, 
before they are placed in the output data set. The control program uses the length 

specified in the DCBLRECL field as the length of the record currently being stored. 
Control is not returned to the user’s program until the control program has processed the 
record. 


The PUTX macro instruction can be used only in the output mode for SYSIN or 
SYSOUT data sets. 


The PUTX macro instruction is written as follows: 


[ symbol ] | PUTX dcb address 
[,input dcb address | 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for a data set 
opened for output. 


input dcb address —RX-Type Address, (2-12), or (0) 
The input dcb address operand specifies the address of a data control block opened 
for input. The PUTX macro instruction can be used for the following modes: 


Output Mode: This mode is used with QSAM only. The input dcb address operand 
specifies the address of the data control block opened for input. If this operand is 
omitted, the system assumes that register 0 contains the input dcb address. 


Update Mode: The input dcb address operand is omitted for update mode. 


PUTX Routine Exit 


The error analysis (SYNAD) routine is given control if the operation is not completed 
satisfactorily. The contents of the registers when the error analysis routine is given 
control are described in Appendix A. 
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READ—Read a Block (BDAM) 


The READ macro instruction causes a block to be retrieved from a data set and placed in 
a designated area of storage. Control may be returned to the problem program before the 
block is retrieved. The input operation must be tested for completion using a CHECK or 
WAIT macro instruction. A data event control block, shown.in Appendix A, is 
constructed as part of the macro expansion. 


The standard form of the READ macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 


[ symbol | decb name 
» lype 
»dcb address 
s{area address | ‘S’} 


ilength |‘S’} 

»ikey address |<‘S’ | 0} 
» block address 

[,next address | 





dech name —symbol 
The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 


type —{DI[F | X][R | RU]} 


{DK[F | X][R | RU]} 
The type operand is coded in one of the combinations shown above to specify the 
type of read operation and the optional services performed by the system: 


DI 
Specifies that the data and key, if any, are to be read from a specific device 
address. The device address, which can be designated by any of the three 
addressing methods, is supplied by the block address operand. 


DK 
Specifies that the data (only) is to be read from a device address identified by a 
specific key. The key to be used as a search argument must be supplied in the area 
specified by the key address operand; the search for the key starts at the device 
address supplied in the area specified by the block address operand. The 
description of the DCB macro instruction, LIMCT operand, contains a 
description of the search. 


F 
Requests that the system provide block position feedback into the area specified 
by the block address operand. This character can be coded as a suffix to DI or 
DK as shown above. 

xX 


Requests exclusive control of the data block being read, and it requests that the 
system provide block position feedback into the area specified by the block 
address operand. The descriptions of the WRITE and RELEX macro instructions 
contain a description of releasing a data block that is under exclusive control. This 
character can be coded as a suffix to DI or DK as shown above. 
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Requests that the system provide next address feedback into the area specified by 
the next address operand. When R is coded, the feedback is the relative track 
address of the next data record. This character can be coded as a suffix to DI or 
DK, DIF, DIX, DKF, or DKX as shown above, but it can be coded only for use 
with variable-length spanned records. 


RU 
Requests that the system provide next address feedback into the area specified by 
the next address operand. When RU is coded, the feedback is the relative track 
address of the next capacity record (RO) or data record whichever occurs first. 
These characters can be coded as a suffix to DI, DK, DIF, DIX, DKF, or DKX, 
but it can be coded only for use with variable-length spanned records. 


dcb address —A-Type Address or (2-12) 
The dcb address operand specifies the address of the data control block opened for 
the data set to be read. 


area address —A-Type Address, (2-12), or ‘S’ 
The area address operand specifies the address of the area into which the data block 
is to be placed. If ‘S’ is coded instead of an address, dynamic buffering is requested 
(dynamic buffering must also be specified in the MACRF operand of the DCB macro 
instruction). When dynamic buffering is used, the system acquires a buffer and places 
its address in the data event control block. 


length —symbol, decimal digit, absexp, (2-12), or ‘S’ 
The length operand specifies the number of data bytes to be read up to a maximum of 
32,760. If ‘S’ is coded instead of a length, the number of bytes to be read is taken 
from the data control block. 


key address —A-Type Address, (2-12), ‘S’, or 0 
The key address operand specifies the address of the area for the key of the desired 
data block. If the search operation is made using a key, the area must contain the key. 
Otherwise, the key is read into the designated area. If the key is read and ‘S’ was 
coded for the area address, ‘S’ can also be coded for the key address; the key and data 
are read sequentially into the buffer acquired by the system. If the key is not to be 
read, specify 0 instead of an address or ‘8’. 


block address——A-Type Address or (2-12) 
The block address operand specifies the address of the area containing the relative 
block address, relative track address, or actual device address of the data block to be 
retrieved. The device address of the data block retrieved is placed in this area if block 
position feedback is requested. The length of the area that contains the address 
depends on whether the feedback option (OPTCD=F) has been specified in the data 
control block and if the READ macro instruction requested feedback. 


If OPTCD=F has been specified, feedback (if requested) is in the same form as was 
originally presented by the READ macro instruction, and the field can be either three 
or eight bytes long depending on the type of addressing. 


If OPTCD=F has not been specified, feedback (if requested) is in the form of an 
actual device address, and the field must be eight bytes long. 
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next address —A-Type Address or (2-12) 
The next address operand specifies the address of the storage area where the system 
places the relative address of the next record. The length operand must be specified as 
‘S’. When the next address operand is specified, an R or RU must be added to the 
type operand (for example, DIR or DIRU). The R indicates that the next address 
returned is the next data record. RU indicates that the next address returned is for the 
next data or capacity record, whichever occurs first. The next address operand can be 
coded only for use with variable-length spanned records. 
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READ—Read a Block of Records (BISAM) 


The READ macro instruction causes an unblocked record, or a block containing a 
specified logical record, to be retrieved from a data set. The block is placed in a 
designated area of storage, and the address of the logical record is placed in the data 
event control block. The data event control block is constructed as part of the macro 
expansion and is described in Appendix A. 


Control may be returned to the problem program before the block is retrieved. The input 
operation must be tested for completion using a WAIT or CHECK macro instruction. 


The standard form of the READ macro instruction is written as follows for BISAM (the 
list and execute forms are shown following the descriptions of the standard form): 


[ symbol | decb name 


, type 
»dcb address 


,{area address | ‘S’} 
ilength | ‘S’} 
»key address 





decb name —symbol 
The decb name operand specifies the name assigned to the data event control block 
(DECB) created as part of the macro expansion. 


type —{K | KU} 
The type operand is coded as shown to specify the type of read operation: 
- | 


Specifies normal retrieval. 


KU 
Specifies that the record retrieved is to be updated and returned to the data set; the 
system saves the device address to be returned. 


When an ISAM data set is being updated with a READ KU macro instruction and 
a WRITE K macro instruction, both the READ and WRITE macro instructions 
must refer to the same data event control block. This update operation can be 
performed by using a list-form instruction to create the list (data event control 
block) and by using the execute form of the READ and WRITE macro instructions 
to refer to the same list. 


dcb address —A-Type Address or (2-12) 
The dcb address operand specifies the address of the data control block for the 
opened data set to be read. 


area address —A-Type Address, (2-12), or ‘S’ 
The area address operand specifies the address of the area into which the data block 
is placed. The first sixteen bytes of this area are used by the system and do not 
contain information from the data block. The area address must specify a different 
area than the key address. Dynamic buffering is specified by coding ‘S’ instead of an 
address; the address of the acquired storage area is returned in the data event control 
block. Indexed sequential buffer and work area requirements are described in OS/VS 
Data Management Services Guide. 


length —symbol, decimal digit, absexp, (2-12), or ‘S’ 
The length operand specifies the number of bytes to be read up to a maximum of 


32,760. If ‘S’ is coded instead of a length, the number of bytes to be read is taken 
from the count field of the record; for blocked records, ‘S’ must be coded. 
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key address-—A-Type Address or (2-12) 
The key address operand specifies the address of the area in the problem program 
containing the key of a logical record in the block that is to be retrieved. When the 
input operation is completed, the storage address of the logical record is placed in the 
data event control block. The key address must specify a different area than the area 
address. 
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READ—Read a Block (BPAM and BSAM) 


The READ macro instruction causes a block to be retrieved from a data set and placed in 
a designated area of storage. Control may be returned to the problem program before the 
block is retrieved. The input operation must be tested for completion using a CHECK 
macro instruction. A data event control block, shown in Appendix A, is constructed as 
part of the macro expansion. 


If the OPEN macro instruction specifies UPDAT, both the READ and WRITE macro 
instruction must refer to the same data event control block. Refer to the list form of the 
READ or WRITE macro instruction for a description of how to construct a data event 
control block; refer to the execute form of the READ or WRITE macro instruction for a 
description of how to modify an existing data event control block. 


For information on additional operands for the READ macro for the 1275 or 1419, see 
OS Data Management Services and Macro Instructions for IBM 1419/1275. 


For information on additional operands for the READ macro instruction for the 3886, 
see OS/VS IBM 3886 Optical Character Reader Model 1 Reference. 


The standard form of the READ macro instruction is written as follows (the list and 


execute forms are shown following the descriptions of the standard form instructions): 


[ symbol | decbh name 
»lype 


,acb address 
,area address 
sli length | ‘S’}] 





dech name—symbol 
The decb name operand specifies the name assigned to the data event control block 
(DECB) created as part of the macro expansion. 


type —{SF | SB} 
The type operand is coded as shown to specify the type of read operation: 


SF 
Specifies normal, sequential, forward retrieval. 


SB 
Specifies a read backward operation; this operand can be specified only for 
magnetic tape with format-F or format-U records. 


dcb address—-A-Type Address or (2-12) 
The dcb address operand specifies the address of the data control block for the 
opened data set to be read. 


area address —A-Type Address or (2-12) 
The area address operand specifies the address of the problem program area into 
which the record is placed. When a READ SB macro instruction is issued, the area 
address must be the address of the last byte of the area into which the record is read. 
If the data set contains keys, the key is read into the buffer followed by the data. 


length —symbol, decimal digit, absexp, (2-12), or ‘S’ 
The length operand specifies the number of data bytes to be read, to a maximum of 
32,760. Uf the data is translated from ASCII code to EBCDIC code, the maximum 
number of bytes that can be read is 2048. A number can be coded only for format-U 
records. The number of bytes to be read is taken from the data control block if ‘S’ is 
coded instead of a number. (This operand is ignored for format-F or format-V 
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records.) For format-D records only, the length of the record just read is automatically 
inserted into the DCBLRECL field if BUFOFF=(L) is not specified in the data 
control block. 
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READ—Read a Block (Offset Read of Keyed BDAM 
Data Set Using BSAM) 


The READ macro instruction causes a block to be retrieved from a data set and placed in 
a designated area of storage. The data set is a BDAM data set and its record format is 
unblocked variable-length spanned records. BFTEK=R must be specified in the data 
control block. Control may be returned to the problem program before the block is 
retrieved. The input operation must be tested for completion using a CHECK macro 
instruction. A data event control block, shown in Appendix A, is constructed as part of 
the macro expansion. 


The standard form of the READ macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 


[symbol ] decb name 
SF 


»dcb address 
,area address 





decb name —symbol 
The dech name operand specifies the name assigned to the data event control block 
(DECB) created as part of the macro expansion. 


SF 
Specifies normal, sequential, forward retrieval. 


dch address —A-Type Address or (2-12) 
The dcb address operand specifies the address of the data control block for the 
opened BDAM data set to be read. 


area address —A-Type Address or (2-12) 
The area address operand specifies the address of the area into which the record is 
placed. 


When a spanned BDAM data set is created with keys, only the first segment of a record 
has a key; successive segments do not. When a spanned record is retrieved by the READ 
macro instruction, the system places a segment in a designated area addressed by the 
area address operand. The problem program must assemble all the segments into a 
logical record. Since only the first segment has a Key, the successive segments are read 
into the designated area offset by key length to ensure that the block-descriptor word 
and the segment-descriptor word are always in the same relative position. 
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READ—List Form 


The list form of the READ macro instruction is used to construct a data management 
parameter list in the form of a data event control block (DECB). Refer to Appendix A 
for a description of the various fields of the DECB for each access method. 


The description of the standard form of the READ macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates the operands used for each access method, as well as the meaning of ‘S’ when 
coded for the area address, length, and key address operands. For each access method, 
‘S’ can be coded only for those operands for which it can be coded in the standard form 
of the macro instruction. The format description below indicates the optional and 
required operands in the list form only. 


The list form of the READ macro instruction is written as follows: 


[ symbol | decb name 
»lype 
sLdcb address | 
s|area address | ‘S’] 


sl length | ‘S’] 

sl key address | ‘S’] 
| block address | 
sl next address | 
JMF=L 





dech name —symbol 

type —Code one of the types shown in the standard form 
dcbh address —A-Type Address or ‘S’ 

area address —A-Type Address or ‘S’ 

length —symbol, decimal digit, absexp, or ‘S’ 

key address—A-Type Address or ‘S’ 

block address —A-Type Address 

next address —A-Type Address 


MF=L—Coded as shown 
The MF=L operand specifies that the READ macro instruction is used to create a 
data event control block that can be referenced by an execute-form instruction. 
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READ—Execute Form 


A remote data management parameter list (data event control block) is used in, and can 
be modified by, the execute form of the READ macro instruction. The data event control 
block can be generated by the list form of either a READ or WRITE macro instruction. 


The description of the standard form of the READ macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates the operands used for each access method, as well as the meaning of ‘S’ when 
coded for the area address, length, and key address operands. For each access method, 
‘S’ can be coded only for those operands for which it can be coded in the standard form 
of the macro instruction. The format description below indicates the optional and 
required operands in the execute form only. 


The execute form of the READ macro instruction is written as follows: 


[ symbol | decb address 
»lype 
sl dcb address | 
slarea address | ‘S’] 
sl length | ‘S’] 
sLkey address | ‘S’] 
| block address | 
| next address | 
MF=E 


decb address —RX-Type Address or (2-12) 

type —Code one of the types shown in the standard form 
dcb address —RX-Type Address or (2-12) 

area address —RX-Type Address, (2-12), or ‘S’ 
length-—symbol, decimal digit, absexp, (2-12), or ‘S’ 

key address —RX-Type Address, (2-12), or ‘S’ 

block address —RX-Type Address, or (2-12) 

next address —RX-Type Address or (2-12) 


MF=E—Coded as shown 
The MF=E operand specifies that the execute form of the READ macro instruction is 
used, and that an existing data event control block (specified in the decb address 
operand) is used by the access method. 
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REILEX—Release Exclusive Control (BDAM) 


The RELEX macro instruction causes release of a data block from exclusive control. The 
block must have been requested in an earlier READ macro instruction which specified 
either DIX and DKX. : 


Note: A WRITE macro instruction that specifies either DIX or DKX can also be used to 
release exclusive control. 


The RELEX macro instruction is written as follows: 










[ symbol | | RELEX D 
»dcb address 


yblock address 


D 
Specifies direct access. 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for a BDAM 
data set opened for processing. The dcb address operand must specify the same data 
control block as designated in the associated READ macro instruction. 


block address —RX-Type Address, (2-12), or (0) 
The block address operand specifies the address of the area containing the relative 
block address, relative track address, or actual device address of the data block being 
released. The block address operand must specify the same area as designated in the 
block address operand of the associated READ macro instruction. 


Completion Codes 


When the system returns control to the problem program, the low-order byte of register 
15 contains one of the following return codes; the three high-order bytes of register 15 
are set to zero. 


Hexadecimal 
Code Meaning 


00 Operation completed successfully. 
04 The specified data block was not in the exclusive control list. 
08 The relative track address, relative block address, or actual device address was not within 


the data set. 
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RELSE—Release an Input Buffer (QISAM and QSAM 


Input) 


The RELSE macro instruction causes immediate release of the current input buffer. The 
next GET macro instruction retrieves the first record from the next input buffer. For 
variable-length spanned records (QSAM), the input data set is spaced to the next 
segment which starts a logical record in a subsequent block. Thus, one or more blocks of 
data or records may be skipped. The RELSE macro instruction is ignored if a buffer has 
just been completed or released, if the records are unblocked, or if issued for a SYSIN 
data set. | | a 


The RELSE macro instruction is written as follows: 


| [ symbol | | RELSE dcbh address 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the 
opened input data set. | — 
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SETL—Set Lower Limit of Sequential Retrieval 
(QISAM Input) 


The SETL macro instruction causes the control program to start processing the next 
input request at the specified record or device address. Sequential retrieval of records 
using the GET macro instruction continues from that point until the end of the data set is 
encountered or a CLOSE or ESETL macro instruction is issued. An ESETL macro 
instruction must be issued between SETL macro instructions that specify the same data 
Set. 


The SETL macro instruction can specify that retrieval is to start at the beginning of the 
data set, at a specific address on the device, at a specific record, or at the first record of a 
specific class of records. For additional information on SETL functions, see OS/VS 
Data Management Services Guide. 


The SETL macro instruction is written as follows: 











[symbol] | SETL dcbh address 


K[H], lower limit address 
KC, lower limit address 
KD[H], /ower limit address 
sKCD, lower limit address 
1, lower limit address 


AD, lower limit address 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block opened for 
the indexed sequential data set being processed. 


The following operands are coded as shown, and they specify the starting point and type 
of retrieval: 


K 
Specifies that the next input operation begins at the record containing the key 
specified in the lower-limit address operand. 


KC 
Specifies that the next input operation begins at the first record of the key class 
specified in the lower-limit address operand. If the first record of the specified key 
class has been deleted, retrieval begins at the next nondeleted record regardless of key 
class. 


H 
This option, used with either K or KD, specifies that, if the key in the lower-limit 
address operand is not in the data set, retrieval begins at the next higher key. The 
character H cannot be coded with the key class operands (KC and KCD). 
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KD 
Specifies that the next input operation begins at the record containing the key 
specified in the lower-limit address operand, but only the data portion of the record is 
retrieved. This operand is valid only for unblocked records. 


KCD 
Specifies that the next input operation begins at the first record of the key class 
specified in the lower-limit address operand, but only the data portion of the record is 
retrieved. This operand is valid only for unblocked records. 


Specifies that the next input operation begins with the record at the actual device 
address specified in the lower-limit address operand. 


ID 
Specifies that the next input operation begins with the record at the actual device 
address specified in the lower-limit address operand, but only the data portion of the 
record is retrieved. This operand is valid only for unblocked records. 


B 
Specifies that the next input operation begins with the first record in the data set. 


BD 
Specifies that the next input operation begins with the first record in the data set, but 
only the data portion is retrieved. This operand is valid only for unblocked records. 


lower limit address —RX-Type Address, (2-12), or (0) 
The lower-limit address operand specifies the address of the area containing the key, 
key class, or actual device address that designates the starting point for the next input 
operation. If I or ID has been specified, this area must contain the actual device 
address (in the form MBBCCHHR) of a prime data record; the other types require 
that the key or key class be contained in this area. 


SETL Exit 


The error analysis (SYNAD) routine is given control if the operation could not be 
completed successfully. The exceptional condition code and general registers are set as 
shown in Appendix A. If the SETL macro instruction is not reissued, retrieval starts at 
the beginning of the data set. 
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SETPRT—Load UCS and FCB Images (BSAM, 
QSAM, and EXCP) 


The SETPRT macro instruction is used with printers that have a universal character set 
(UCS) buffer or a forms control buffer (FCB). When a SETPRT macro instruction is 
issued, UCS and FCB images are fetched from the image library and loaded from storage 
into their respective buffers. The SETPRT macro instruction is also used to block or 
unblock printer data checks. 


IBM character sets and forms control images are included in the image library at system 
generation; user-defined character sets and forms control images can be added to the 
image library as described in OS/VS1 Data Management for System Programmers 
and OS/VS2 System Programming Library: Data Management. The FCB (EXLST) 
parameter of the DCB macro instruction can be used to specify the address of an FCB 
image. 


When BSAM is being used, all write operations must be checked for completion before 
the SETPRT macro instruction is issued; any incomplete write operations are purged. 
Issuing the SETPRT macro instruction for a device other than an on-line UCS printer 
results in a NOP instruction. 


Note: SETPRT with EXCP programming is valid only for VS2 systems. 


The standard form of the SETPRT macro instruction is written as follows (the list and 
execute forms are shown following the standard form): 









[symbol | | SETPRT dcbaddr 


sUCS=(csc [,F | FV | »V)) 
[|,FCB=(imageid[,V | ,A])] 
[,OPTCD={B | U}] 






FCB=(imageid[,V | ,Al) 


dcbaddr —A-Type Address or (2-12) 
The dcbaddr operand specifies the address of the data control block for the data set to 
be printed; the data set must be opened for output before the SETPRT macro 
instruction is issued. 


UCS= A character code with options 
The UCS operand specifies that the UCS buffer is to be loaded from the image 
library. When the UCS operand is specified, the FCB and OPTCD operands can also 
be specified. The possible specifications are: 


csc (character set code) 
The csc operand specifies the character set to be loaded. A character set is 
identified by a 1-4 character code. Codes for standard IBM character sets are as 
follows: 
1403 Printer: AN, HN, PCAN, PCHN, PN, QN, QNC, RN, SN, TN, XN, and YN 
3211 Printer: Al1, H11, G11,P11, and T11 
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For descriptions of the standard IBM character sets, refer to OS/VS1 System 
Generation Reference or OS/VS2 System Programming Library: System 
Generation Reference; codes for user-designed character sets are defined by the 
installation. 


F or FOLD 
Specifies that the character set image is to be loaded in the fold mode. The fold 
mode is most often used when the EBCDIC code for lowercase alphabetic 
characters is printed as uppercase characters by a print train with lowercase type. 


V or VERIFY 
Requests that the character set image be displayed on the printer for visual 
verification. 


FCB= A character code with options 

The FCB operand specifies that the forms control buffer (FCB) is to be loaded from 

the image library. When the FCB operand is specified, the OPTCD operand can also 

be specified. The possible specifications are: 

imageid 
The imageid operand specifies the forms control image to be loacied. A forms 
control image is identified by a 1-4 character code. IBM-supplied images are 
identified by imageid value of STD1 and STD2; user-designed forms control 
images are defined by the installation. For descriptions of the standard forms 
control images, refer to OS/VS1 Data Management for System Programmers ot 
OS/VS2 System Programming Library: Data Management. 


V or VERIFY 
Requests that the forms control image be displayed on the printer for visual 
verification. This operand allows forms alignment using the WTOR macro 
instruction. 


A or ALIGN 
Allows forms alignment using the WIOR macro instruction. 


OPTCD= A printer option code 
The OPTCD operand specifies whether UCS printer data checks are blocked or 
unblocked and if the printer is to operate in fold or normal mode. The possible 
specifications are: 


B 
Specifies that UCS printer data checks are blocked; this option updates the 
DCBOPTCD field of the data control block. 


U 
Specifies that UCS printer data checks are unblocked; this option updates the 
DCBOPTCD field of the data control block. 


F or FOLD 
Specifies that printing is in fold mode. 


U or UNFOLD 
Specifies that printing is in normal mode; this operand causes fold mode to revert 
to normal mode. 
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Completion Codes 


After the SETPRT macro instruction is executed, a return code is placed in register 15, 
and control is returned to the instruction following the SETPRT macro instruction. Bits 
16-23 indicate the result of the attempt to load the forms control buffer (FCB). Bits 
24-31 indicate the result of the attempt to load a universal-character-set (UCS) buffer. 
For completion codes 18, 1C, 20, and 24, bits 24-31 apply to both FCB and UCS 
loading. The codes in the following table are in hexadecimal. 


Bits 16-23 
FCB Code 


00 
04 


08 


OC 
10 


14 


Bits 24-31 
UCS Code 


00 
04 


08 


OC 


10 


14 


Bits 24-31 
FCB and 
UCS Code 


18 


1C 


20 


24 


Meaning 
Successful completion. 
The operator canceled the load for one of the following reasons: 


e The image could not be found in the image library. 

¢« For a UCS image, the requested chain or train was 
not available. 

¢ For FCB, forms could not be aligned to match the 
buffer. 


A permanent I/O error was detected when the BLDL macro instruction was 
issued to locate the image in the image library. 


A permanent I/O error was detected while loading the FCB/UCS buffer. 


A permanent I/O error was detected when an attempt was made to display 
the character set image or forms control image on the printer for visual 
verification. 


The operator canceled the load because the wrong image was displayed for 
visual verification. 


No operation was performed for one of the following reasons: 


« The data control block was not open. 

¢« The data control block was not valid for a sequential 
data set. 

¢ The SETPRT parameter list was not valid. 

¢« The output device was not a UCS printer. 

¢ SETPRT was used with EXCP programming (VS1 only). 


No operation was performed because an uncorrectable error occurred in a 
previously initiated output operation. The error analysis (SYNAD) routine is 
entered when the next PUT or CHECK macro instruction is issued. 


No operation was performed because an uncorrectable error occurred when 
the Block Data Check or Reset Block Data Check command was issued by 
SETPRT. 


Not enough space has been provided for the IMAGELIB control blocks. 
Increase the amount of space allocated for the job step. 


SYS1.IMAGELIB cannot be opened to load the specified UCS/FCB image. 
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SETPRT—List Form 


The list form of the SETPRT macro instruction is used to construct a data management 
parameter list. 


The description of the standard form of the SETPRT macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are totally optional and those required in at least one of the 
pair of list and execute forms. The format description below indicates the optional and 
required operands for the list form only. 


The list form of the SETPRT macro instruction is written as follows: 





[ symbol] | SETPRT [ dcbadar | 


sUCS=(csc [,F | F,V | V1) 
[,FCB=(imageid[,V | ,A])] 
[,OPTCD={B | U}] 














FCB=(imageid|[,V | ,A]) 


dcbaddr —A-Type Address 


UCS:: A character code with options 
It is coded as described in the standard form of the macro instruction. 


FCB=: A character code with options 
It is coded as described in the standard form of the macro instruction. 


OPTCD= A printer option code 
It is coded as described in the standard form of the macro instruction. 
MF=L 
The MF=L operand specifies that the list form of the macro instruction is used to 


create a parameter list that can be referenced by an execute form of the SETPRT 
macro instruction. 
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yp? 


SETPRT—Execute Form 


A remote data management parameter list is referred to, and can be modified by, the 
execute form of the SETPRT macro instruction. 


The description of the standard form of the SETPRT macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates which operands are totally optional and those required in at least one of the 
pair of list and execute forms. The format description below indicates the optional and 
required operands for the execute form only. 


The execute form of the SETPRT macro instruction is written as follows: 





[ symbol | | SETPRT [ dcbadadr | 


UCS=(csc [,F | FV | ,,V1) 
[ FCB=( imageid [,V | »Al)] 
[,OPTCD= {B | U}] 


»FCB=(imageid [,V | ,A]) 
JMF=(E,{ data management list address | (1)}) 


dcbaddr —RX-Type Address or (2-12) 


UCS:= A character code with options 
It is coded as shown in the standard form of the macro instruction. 


FCB-= A character code with options 
It is coded as shown in the standard form of the macro instruction. 


OPTCD= A printer option code 
It is coded as shown in the standard form of the macro instruction. 


MF=(E,{ data management list address |(1)} 
This operand specifies that the execute form of the SETPRT macro instruction is 
used, and an existing data management parameter list is used. 


E-—Coded as shown 
data management list address —RX-Type Address, (2-12), or (1) 
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STOW—Update Partitioned Data Set Directory 
(BPAM) 


The STOW n macro instruction causes the system to update a partitioned dis set dietary 
by adding, changing, replacing, or deleting an entry in the directory. Only one entry can 
be updated at a time using the STOW macro instruction. If the entry to be added or 
replaced is a member name, the system writes an end-of-data indication following the 
member. All input/output operations using the same data control block must have 
previously been tested for completion. 


The STOW macro instruction is written as follows: 


[symbol]|STOW . dcb address 


s list address 
[, directory action | 





dcb address RX Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data eoitiol block for the 
opened partitioned data set. The STOW macro instruction can be used only when the 
data set is opened for OUTPUT, UPDAT or OUTIN (BSAM). 


list address —RX-Type Address, (2- 12), or (0) 
The list address operand specifies the address of the area containing the information 
required by the system to maintain the partitioned data set directory. The size and 
format of the area depend on the directory action requested as follows: 


Adding or Replacing a Directory Entry: The list address operand must specify an area 
at least 12 bytes long and beginning on a halfword boundary. The following 
illustration shows the format of the area: 


List Address 


Length 
Bytes 





NAME: Specifies the member name or alias being added or replaced. The name must 
begin in the first byte of the field and be padded on the right with blanks, if necessary, 
to complete the 8-byte field. 


TT: Specifies the relative track number on which the veune of the data set is 
located. 


R: Specifies the relative block (record) number on the track identified by TT. 


Note: The TTR field shown above must be supplied by the problem program if an 
alias (alias bit is 1) is being added or replaced. The system supplies the TTR field 
when a member name is being added or replaced. 
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C: Specifies the type of entry (member or alias) for the name, the number of note list 
fields (TTRNs), and the length in halfwords, of the user data field. The following 
describes the meaning of the eight bits: 


Bit Meaning 

0=0 Indicates a member name. 

0=1 Indicates an alias. : 
land2 Indicate the number of TTRN fields (maximum of three) in the user data field. 
3-7 ' Indicate the total number of halfwords in the user data field. 


Deleting a Directory Entry: The list address operand must specify an 8-byte area that 
contains the member name or alias to be deleted. The name must begin in the first 
byte of the area and be padded on the right with blanks, if necessary, to complete the 
eight bytes. 


Changing the Name of a Member: The /ist address operand must specify the address 
of a 16-byte area; the first 8 bytes contain the old member name or alias, and the 
second 8 bytes contain the new member name or alias. Both names must begin in the 
first byte of their 8-byte area and be padded on the right with blanks, if necessary, to 
complete the 8-byte field. 


directory action —[A|C|D|R] 
If the directory action operand is not coded, A (add an entry) is assumed. The 
operand is coded as shown to specify the type of directory action: 


A 
Specifies that an entry is to be added to the directory. 


C 
Specifies that the name of an existing member or alias is to be changed. 


D | 
Specifies that an existing directory entry is to be deleted. 


R 
Specifies that an existing directory entry is to be replaced by a new directory entry. 
If R is coded but the old entry is not found, the new entry is added to the directory 
and a completion code of X‘08’ is returned in register 15. 
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Completion Codes 


When the system returns control to the problem program, registers 15 and 0 contain one 
of the following return codes in the low-order byte; the three high-order bytes of both 
registers are set to zero. 


Hexadecimal 
Return Code 


(Reg. 15) 
00 


04 


08 


0C 


10 


14 


18 


Hexadecimal 
Reason Code 


(Reg. 0) 
00 
01 


02 


A 


The update of the 
directory was 
completed 
successfully. 


The directory 
already contains 
the specified 
name. 


No space left in 
the directory. 
The entry could 
not be added, 
replaced, or 
changed. 


A permanent input 
or output error 
was detected. 
Control is not 
given to the 

error analysis 
(SYNAD) routine. 


The specified 
data control 
block is not 

open or is opened 
for input. 


Insufficient 
virtual storage 
was available 

to perform the 
STOW function. 


Meaning 


Directory Action 


R 


The update of the 
directory was 
completed 
successfully. 


The specified 
name could not 
be found. 


No space left in 
the directory. 
The entry could 
not be added, 
replaced, or 
changed. 


A permanent input 
or output error 
was detected. 
Control is not 
given to the 

error analysis 
(SYNAD) routine. 


The specified 
data control 
block is not 

open or is opened 
for input. 


Insufficient 
virtual storage 
was available 

to perform the 
STOW function. 


D 


The update of the 
directory was 
completed 
successfully. 


——— 


The specified 
name could not 
be found. 


A permanent input 
or output error 
was detected. 
Control is not 
given to the 

error analysis 
(SYNAD) routine. 


The specified 
data control 
block is not 

open or is opened 
for input. 


Insufficient 
virtual storage 
was available 

to perform the 
STOW function. 


C 


The update of the 
directory was 
completed 
successfully. 


The directory 
already contains 
the specified 
new name. 


The specified old 
name could not 
be found. 


No space left in 
the directory. 
The entry could 
not be added, 
replaced, or 
changed. 


A permanent input 
or output error 
was detected. 
Control is not 
given to the 

error analysis 
(SYNAD) routine. 


The specified 
data control 
block is not 

open or is opened 
for input. 


Insufficient 
virtual storage 
was available 

to perform the 
STOW function. 


Reason code is not applicable. (Returned with all return codes except 10.) 
All functions; the permanent I/O error occurred while reading or writing directory 


blocks. 


Add and replace functions; the permanent I/O error occurred while writing an EOF mark 


after the member. 
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SYNADAF—Perform SYNAD Analysis Function 
(BDAM, BISAM, BPAM, BSAM, EXCP, QISAM, and 
QSAM) 


The SYNADAF macro instruction is used in an error analysis routine to analyze 
permanent input/output errors. The routine can be a SYNAD routine specified in a data 
control block for BDAM, BISAM, BPAM, BSAM, QISAM, QSAM, or a routine that is 
entered directly from a program that uses the EXCP macro instruction. (The EXCP 
macro instruction is described in OS/VSI Data Management for System Programmers 
and OS/VS2 System Programming Library: Data Management.) 


The SYNADAF macro instruction uses register 1 to return the address of a buffer 
containing a message. The message describes the error, and can be printed by a 
subsequent PUT or WRITE macro instruction. The message consists of EBCDIC 
information and is in the form of a variable-length record. The format of the message is 
shown following the descriptions of the SYNADAF operands. 


The system does not use the save area whose address is in register 13. Instead, it provides 
a save area for its own use, and then makes this area available to the error analysis 
routine. The system returns the address of the new save area in register 13 and in the 
appropriate location (word 3) of the previous save area; it also stores the address of the 
previous save area in the appropriate location (word 2) of the new save area. 


The SYNADAF macro instruction passes parameters to the system in registers 0 and 1. 
When used in a SYNAD routine, the SYNADAF macro should be coded at the 
beginning of the routine (refer to Appendix A, Figures 4 through 6). For BISAM and 
QISAM, the SYNAD routine has to set up these parameters as explained under PARM1 
and PARM2. To save these parameters for use by the SYNAD routine, the system stores 
them in a parameter save area that follows the message buffer as shown in the message 
buffer format. The system does not alter the return address in register 14 or the entry 
point address in register 15. 


When a SYNADAF macro instruction is used, a SYNADRLS macro instruction must be 
used to release the message buffer and save areas, and to restore the original contents of 
register 13. 
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The SYNADAF macro instruction is written as follows: 


[symbol]|SYNADAF | ACSMETH= {BDAM 
[| .PARM1= parm register 
[,PARM2= parm register 


{BPAM 
[.PARM1= parm register 
[,.PARM2= parm register 


{BSAM 
[,PARM1= parm register 
[,.PARM2= parm register 


§QSAM 
[.PARM1= parm register 
[|,.PARM2= parm register 


{BISAM 
|, PARM1 = dcbaddr | 
[,PARM2=decb address | 


{EXCP 
[,PARM1=iob address | 


{QISAM 
[,PARM1 = dcbaddr ] 
[.PARM2= parm register | } 





ACSMETH=BDAM, BPAM, BSAM, QSAM, BISAM, EXCP, or QISAM 
The ACSMETH operand specifies the access method used to perform the 
input/output operation for which error analysis is performed. 


PARMI1=parm register, iobaddr, or dcbaddr —(2-12) or (1) 
The PARMI operand specifies the address of information that is dependent on the 
| access method being used. For BDAM, BPAM, BSAM, or QSAM, the operand 
specifies a register that contains the information that was in register 1 on entry to the 
| SYNAD routine. For BISAM or QISAM, the operand specifies the address of the data 
control block; for EXCP, it specifies the address of the input/output block. If the 
operand is omitted, PARM1=(1) is assumed. 


PARM2=parm register —(2-12), (0), or RX-Type Address (only if ACSMETH=QISAM) 

The PARM2 operand specifies the address of additional information that is dependent 

| on the access method being used. For BDAM, BPAM, BSAM, QISAM, and QSAM, 
the operand specifies a register that contains the information that was in register 0 on 
entry to the SYNAD routine. For BISAM, the operand specifies a register that 
contains the information that was in register 1 on entry to the SYNAD routine (the 
address of the DECB). For EXCP, the operand is meaningless and should be omitted. 
If the operand is omitted, except in the case of EXCP, PARM2=(0) is assumed. 


Note: For correctly loading the registers for SYNADAF for BISAM, you may code these 
two instructions before issuing the SYNADAF macro: 


-LR 0,1 GET DECB ADDRESS 
L 1,8(1) GET DCB ADDRESS 
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Completion Codes 


When the system returns control to the problem program, the low-order byte of register 
0 contains one of the following return codes; the three high-order bytes of register 0 are 
set to zero. 


Hexadecimal 
Code Meaning 


00 Successful completion. Bytes 8-13 of the message buffer contain blanks. 
04 Successful completion. Bytes 8-13 of the message buffer contain binary data. 
08 Unsuccessful completion. The message can be printed, but some information is missing in 


bytes 50-127 and is represented by asterisks. If byte 8 is a blank (X‘40’), then bytes 9-13 
are either blanks or are uninitialized. If byte 8 is not a blank, then data was read and bytes 
8-13 of the message buffer contain binary data. 
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Message Buffer Format 


The following illustration shows the format of the message buffer; the address of the 
buffer is returned in register 1. 


8 













Input 
Buffer 
Address 






Message Buffer Input: 
Byte 0 4 eS 


LLbb 11 bb 


Doubleword Output: (Blanks) 
Boundary 
LL= 128; N=124; bb=000 


50 59 


14 50 





a (Blanks) 


75 84 















Jobname Stepname DDname 








84 91 






Operation 
Attempted 






























107 Ga 128 
Unit Record: (Asterisks) Method 
128 
(End of Buffer - 
Relative Block Access — Beginning of 
; a Blanks) 8 8 
Magnetic Tape: _ Number (decimal) Method ( Parameter Save Area 
107 122 128 
nd Actual Track Address and Block Number Access 
Direct Access: (BBCCHHR in hexadecimal format) Method 


Parameter Save Area 
128 132 136 













Parameter Parameter 
Register 0 Register | 
(PARM2) (PARM1) 





Notes: 


e The device type field (bytes 72-73) contains UR for a unit record device, TA for a 
magnetic tape device, or DA for a direct-access device. 


e If a message field (bytes 91-105) is not applicable to the type of error that occurred, it 
contains N/A or NOT APPLICABLE. 


e If no data was transmitted, or if the access method is QISAM, bytes 8-13 contain 
blanks or binary zeros. 


e If the access method is BISAM, bytes 68-70, 84-89, and 107-120 contain asterisks. 


¢ If the access method is BDAM, and if the error was an invalid request, bytes 107-120 
contain EBCDIC zeros. 
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SYNADRLS—Release SYNADAF Buffer and Save 
Areas (BDAM, BISAM, BPAM, BSAM, EXCP, 
QISAM, and QSAM) 


The SYNADRLS macro instruction releases the message buffer, parameter save area, 
and register save area provided by a SYNADAF macro instruction. It must be used to 
perform this function whenever a SYNADAF macro instruction is used. 


When the SYNADRLS macro instruction is issued, register 13 must contain the address 
of the register save area provided by the SYNADAF macro instruction. The control 
program loads register 13 with the address of the previous save area, and sets word 3 of 
that save area to zero. Thus, when control is returned, the save area pointers are the 
same as before the SYNADAF macro instruction was issued. 


The SYNADRLS macro instruction is written as follows: 


[symbol||SYNADRLS | 6 oo | | 


When the system returns control to the problem program, the low-order byte of register 
0 contains one of the following return codes; the three high-order bytes of register 0 are 
set to zero. 





Hexadecimal 
Code Meaning 


00 Successful completion. 

08 Unsuccessful completion. The buffer and save areas were not released; the contents of 
register 13 remain unchanged. Register 13 does not point to the save area provided by the 
SYNADAF macro instruction, or this save area is not properly chained to the previous 
Save area. 
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TRUNC—Truncate an Output Buffer (QSAM 
Output—Fixed- or Variable-Length Blocked Records) 


The TRUNC macro instruction causes the current output buffer to be regarded as full. 
The next PUT or PUTX macro instruction specifying the same data control block uses 
the next buffer to hold the logical record. 


When a variable-length spanned record is being truncated and logical record interface is 
specified (that is, if BFTEK=A is specified in the DCB macro instruction, or if a 
BUILDRCD macro instruction is issued), the system segments and writes the record 
before truncating the buffer. Therefore, the block being truncated is the one that 
contains the last segment of the spanned record. 


The TRUNC macro instruction is ignored if it is used for unblocked records; if it is used 
when a buffer is full, or if it is used without an intervening PUT or PUTX macro 
instruction. 


The TRUNC macro instruction is written as follows: 


[symbol ] acb address | 


dcb address —RX-Type Address, (2-12), or (1) 
The dcb address operand specifies the address of the data control block for the 
sequential data set opened for output. The record format in the data control block 
' must not indicate standard blocked records (RECFM=FBS). 
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WAIT—Wait for One or More Events (BDAM, 
BISAM, BPAM, and BSAM) 


The WAIT macro instruction is used to inform the control program that performance of 
the active task cannot continue until one or more specific events, each represented by a 
different ECB (event control block), have occurred. In the context of this manual, the 
ECBs represent completion of I/O processing associated with a READ or WRITE 
macro. ECBs are located at the beginning of access method DECBs (data event control 
blocks), so that the DECB name provided in READ and WRITE macros is also used for 
WAIT. A description of the ECB is found in “Appendix A” and in OS/VSI System 
Data Areas and OS/VS2 System Programming Library: Debugging Handbook. For 
information on when to use the WAIT macro, see OS/VS Data Management Services 
Guide. 


The control program takes the following action: 


¢ For each event that has already occurred (each ECB is already posted), the count of 
the number of events is decreased by 1. 


e If the number of events is 0 by the time the last event control block 1s checked, 
control is returned to the instruction following the WAIT macro instruction. 


e If the number of events is not 0 by the time the last ECB is checked, control is not 
returned to the issuing program until sufficient ECBs are posted to bring the number 
to 0. Control is then returned to the instruction following the WAIT macro 
instruction. 


e The events will be posted complete by the system when all I/O has been completed, 
temporary errors have been corrected, and length checking has been performed. The 
DECRB is not checked for errors or exceptional conditions, nor are end-of-volume 
procedures initiated. Your program must perform these operations. 


The WAIT macro instruction is written as follows: 


[symbol | | WAIT [number of events | 


{,ECB= addr | ECBLIST= addr } 
| .LLONG={YES | NO}] 





number of events 
Specifies a decimal integer from 0 to 255. Zero is an effective NOP instruction; one is 
assumed if the operand is omitted. The number of events must not exceed the 
number of event control blocks. 


ECB=addr 
Specifies the address of the event control block (or DECB) representing the single 
event that must occur before processing can continue. The operand is valid only if the 
number of events is specified as one or is omitted. 


ECBLIST=addr 
Specifies the address of a virtual storage area containing one or more consecutive 
fullwords on a fullword boundary. Each fullword contains the address of an event 
control block (or DECB); the high-order bit in the last word (address) must be set to 
1 to indicate the end of the list. The number of event control blocks must be equal to 
or greater than the specified number of events. 
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LONG={YES | NO} 
Specifies whether the task is entering a long wait or a regular wait. Normally I/O 
events should not be considered “Jong” unless it is anticipated that operator 
intervention will be required. This operand is valid only for VS2. 


Caution: A job step with all of its tasks in a WAIT condition is terminated upon 
expiration of the time limits that apply to it. 


Access method ECBs are maintained entirely by the access methods and supporting 
control program facilities. The user may inspect access method ECBs, but should never 
modify them. 
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WRITE—Write a Block (BDAM) 


The WRITE macro instruction causes the system to add or replace a block in an existing 
direct data set. (This version of the WRITE macro instruction cannot be used to create a 
direct data set because no capacity record facilities are provided.) Control may be 
returned before the block is written. The output operation must be tested for completion 
using a CHECK or WAIT macro instruction. A data event control block, shown in 
Appendix A is constructed as part of the macro expansion. 


The standard form of the WRITE macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 








decb name 
» type 

,dcb address 

,iarea address | ‘S’} 
silength |‘S’} 

sikey address |‘S’ | 0} 
block address 





[ symbol | | WRITE 










decbh name —symbol 
The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 


type —{DA[F]} 
{DI[F | X]} 
{DK[F | X]} 


The type operand is coded in one of the combinations shown to specify the type of 
write operation and optional services performed by the system: 


DA 
Specifies that a new data block is to be added to the data set in the first available 
space; the search for available space starts at the device address indicated in the 
area specified in the block address operand. Fixed-length records are added to a 
data set by replacing dummy records. Variable-length records are added to a data 
set by using available space on a track. For more information on adding records 
to a direct data set, see OS/VS Data Management Services Guide. The 
description of the DCB macro instruction, LIMCT operand, contains a 
description of the search. 


DI 
Specifies that a data block and key, if any, are to be written at the device address 
indicated in the area specified in the block address operand. Any attempt to write 
a capacity record (RO) is an invalid request when relative track addressing or 
actual device addressing are used, but when relative block addressing is used, 
relative block 0 is the first data block in the data set. 


DK 
Specifies that a data block (only) is to be written using the key in the area 
specified by the key address operand as a search argument; the search for the 
block starts at the device address indicated in the area specified in the block 
address operand. The description of the DCB macro instruction, LIMCT 
operand, contains a description of the search. 
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Requests that the system provide block position feedback into the area specified 
in the block address operand. This character can be coded as a suffix to DA, DI, 
or DK as shown above. 


Requests that the system release the exclusive control requested by a previous 
READ macro instruction and provide block position feedback into the area 
specified in the block address operand. This character can be coded as a suffix to 
DI or DK as shown above. 


dcb address ——A-Type Address or (2-12) 
The dcb address operand specifies the address.of the data control block for the 
opened BDAM data set. 


area address —A-Type Address, (2-12), or ‘S’ 
The area address operand specifies the address of the area that contains the data 
block to be written. ‘S’ can be coded instead of an area address only if the data block 
(or key and data) are contained in a buffer provided by dynamic buffering; that is, ‘S’ 
was coded in the area address operand of the associated READ macro instruction. If 
‘S’ is coded in the WRITE macro instruction, the area address from the READ macro 
instruction data event control block must be moved into the WRITE macro instruction 
data event control block; the buffer area acquired by dynamic buffering is released 
after the WRITE macro instruction is executed. See Appendix A for a description of 
the data event control block. 


length —symbol, decimal digit, absexp, (2-12) or ‘S’ 
The length operand specifies the number of data bytes to be written up to a maximum 
of 32,760. If ‘S’ is coded, it specifies that the system uses the value in the block size 
(DCBBLKSI) field as the length. When undefined-length records are used, if the 
WRITE macro instruction is for update and the length specified differs from the 
original block, the new block will be truncated or padded with binary zeros 
accordingly. The problem program can check for this situation in the SYNAD routine. 


If the Jength operand is omitted for format-U records, no error indication is given 
when the program is assembled, but the problem program must insert a length into the 
data event control block before the WRITE macro instruction is executed. 


key address-—-A-Type Address, (2-12), ‘S’, or 0 
The key address operand specifies the address of the area that contains the key to be 
used. ‘S’ is specified instead of an address only if the key is contained in an area 
acquired by dynamic buffering. If the key is not written or used as a search argument, 
zero is specified instead of a key address. 


block address —A-Type Address or (2-12) 
The block address operand specifies the address of the area that contains the relative 
block address, relative track address, or actual device address used in the output 
operation. The length of the area depends on the type of addressing used and if the 
feedback option (OPTCD=F) is specified in the data control block. 


If OPTCD=F has been specified in the DCB macro and F or X is specified in the 
WRITE macro, then you must provide a relative block address in the form specified 
by OPTCD in the DCB macro. For example, if OPTCD=R is specified, you must 
provide a 3-byte relative block address; if OPTCD=A is specified, you must provide 
an 8-byte actual device address (MBBCCHHR); if neither is specified, you must 
provide a 3-byte relative block address (TTR). 


If OPTCD=F has not been specified in the DCB macro and F or X is specified in the 
WRITE macro, then you must provide an 8-byte actual device address 
(MBBCCHHR) even if relative block or relative track addressing is being used. 
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WRITE—Write a Logical Record or Block of Records 


(BISAM) 


The WRITE macro instruction causes the system to add or replace a record or replace an 
updated block in an existing indexed sequential data set. Control may be returned to the 
problem program before the block or record is written. The output operation must be 
tested for completion using a WAIT or CHECK macro instruction. A data event control 
block, shown in Appendix A, is constructed as part of the macro expansion. 


The standard form of the WRITE macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 










decb name 
» lype 

,»dcb address 

yiarea address | ‘S’} 
silength |‘S’} 

ykey address 


[ symbol | 


decbh name —symbol 
The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 


type —{K | KN} | 
The type operand is coded as shown to specify the type of write operation: 
K 


Specifies that either an updated unblocked record or a block containing an updated 
record is to be written. If the record has been read using a READ KU macro 
instruction, the data event control block for the READ macro instruction must be 
used as the data event control block for the WRITE macro instruction, using the 
execute form of the WRITE macro instruction. 


KN 
Specifies that a new record is to be written, or a variable-length record is to be 
rewritten with a different length. All records or blocks of records read using READ 
KU macro instructions for the same data control block must be written back before 
a new record can be added except when the READ KU and WRITE KN refer to 
the same DECB. 


dcb address —A-Type Address or (2-12) 
The dcb address operand specifies the address of the data control block for the 
opened existing indexed sequential data set. If a block is written, the data control 
block address must be the same as the dcb address operand in the corresponding 
READ macro instruction. 


area address—A-Type Address, (2-12), or ‘S’ 
The area address operand specifies the address of the area containing the logical 
record or block of records to be written. The first sixteen bytes of this area are used 
by the system and should not contain your data. The area address must specify a 
different area than the key address. When new records are written (or when 
variable-length records are rewritten with a different length), the area address of the 
new record must always be supplied by the problem program. This area may be 
altered by the system. ‘S’ may be coded instead of an address only if the block of 
records is contained in an area provided by dynamic buffering; that is, ‘S’ was coded 
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for the area address operand in the associated READ KU macro instruction. This 
area is released after execution of a WRITE macro instruction using the same DECB. 
The area can also be released by a FREEDBUF macro instruction. 


The following illustration shows the format of the area: 


Area 
Address 








Control 
Program 


Use Logical Record (WRITE KN) or Block of Records (WRITE K) 


Indexed sequential buffer and work area requirements are discussed in OS/VS Data 
Management Services Guide. 


length —symbol, decimal digit, absexp, (2-12) or ‘S’ 
The length operand specifies the number of data bytes to be written, up to a 
maximum of 32,760. Specify ‘S’ unless a variable-length record will be rewritten with 
a different length. 


key address —A-Type Address or (2-12) 
The key address operand specifies the address of the area containing the key of the 
new or updated record. The key address must specify a different area than the area 
address. For blocked records, this is not necessarily the high key in the block. For 
unblocked records, this field should not overlap with the work area specified in the 
MSWA parameter of the DCB macro instruction. 


Note: When new records are written, the key area may be altered by the system. 
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WRITE—Write a Block (BPAM and BSAM) 


The WRITE macro instruction causes the system to add or replace a block in a sequential 
or partitioned data set being created or updated. Control may be returned to the problem 
program before the block is written. The output operation must be tested for completion 
using the CHECK macro instruction. A data event control block, shown in Appendix A, 
is constructed as part of the macro expansion. 


If translation from EBCDIC code to ASCII code is requested, issuing multiple WRITE 
macro instructions for the same record causes an error because the first WRITE macro 
instruction issued causes the output data in the output buffer to be translated into ASCII 
code. 


If the OPEN macro instruction specifies UPDAT, both the READ and WRITE macro 
instructions must refer to the same data event control block. Refer to the list form of the 
READ or WRITE macro instruction for a description of how to construct a data event 
control block; refer to the execute form of the READ or WRITE macro instruction for a 
description of modifying an existing data event control block. 


The standard form of the WRITE macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 


[ symbol | decb name 
SF 


»dcb address 
,area address - 
[, length | ,‘S’] 





decbh name —symbol 


The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 


SF 
Specifies normal, sequential, forward operation. 


_dcb address ——A-Type Address, or (2-12) 
The dcb address operand specifies the address of the data control block for the 
opened data set being created or processed. If the data set is being updated, the data 
control block address must be the same as the dcb address. operand in the 
corresponding READ macro instruction. 


area address—A-Type Address or (2-12) 
The area address operand specifies the address of the area that contains the data 
block to be written; if a key is written, the key must precede the data in the same area. 


length —symbol, decimal digit, absexp, (2-12) or ‘S’ 
The length operand specifies the number of bytes to be written; this operand is 
specified for only undefined-length records (RECFM=VU) or ASCII records 
(RECFM=D) when the DCB BUFOFF operand is zero. If the data is to be translated 
from EBCDIC code to ASCII code, the maximum length is 2,048; otherwise, the 
maximum length is 32,760 bytes. ‘S’ can be coded to indicate that the value specified 
in the block size (DCBBLKSI) field of the data control block is used as the length to 
be written. The /ength operand should be omitted for all record formats except 
format-U and format-D (when BUFOFF=0). 
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If the length operand is omitted for format-U or format-D (with BUFOFF=0) 
records, no error indication is given when the program is assembled, but the problem 
program must insert a length into the data event control block before the WRITE 
macro is issued. 
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WRITE—Write a Block (Create a BDAM Data Set with BSAM) 


The WRITE macro instruction causes the system to add a block to the direct data set 
being created. For fixed-length blocks, the system writes the capacity record 
automatically when the current track is filled; for variable and undefined-length blocks, a 
WRITE macro instruction must be issued for the capacity record. Control may be 
returned before the block is written. The output operations must be tested for completion 
using a CHECK macro instruction. A data event control block, shown in Appendix A, is 
constructed as part of the macro expansion. 


The standard form of the WRITE macro instruction is written as follows (the list and 
execute forms are shown following the descriptions of the standard form): 
















decb name 
»lype 

»acb address 
,area address 
[,/ength | ,‘S’] 
[,next address | 


[symbol | | WRITE 


decbh name—symbol 
The decb name operand specifies the name assigned to the data event control block 
created as part of the macro expansion. 


type —{SF | SFR | SD | SZ} 
The type operand is coded as shown, to specify the type of write operation performed 
by the system: 


SF 
Specifies that a new data block is to be written in the data set. 


SFR 
Specifies that a new variable-length spanned record is to be written in the data set, 
and next address feedback is requested. This operand can be specified only for 
variable-length spanned records (BFTEK=R and RECFM=VS are specified in the 
data set control block). 


SD 
Specifies that a dummy data block is to be written in the data set; dummy data 
blocks can be written only when fixed-length records with keys are used. 


SZ 
Specifies that a capacity record (RO) is to be written in the data set; capacity 
records can be written only when variable-length or undefined-length records are 
used. 


dcb address —A-Type Address or (2-12) 
The dcb address operand specifies the address of the data control block opened for 
the data set being created. DSORG=PS (or PSU) and MACRF=WL must be 
specified in the DCB macro instruction to create a BDAM data set. 


area address —A-Type Address or (2-12) 
The area address operand specifies the address of the area that contains the data 
block to be added to the data set. If keys are used, the key must precede the data in 
the same area. For writing capacity records (SZ), the area address is ignored and can 
be omitted (the system supplies the information for the capacity record). For writing 
dummy data blocks (SD), the area need be only large enough to hold the key plus one 
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data byte. The system constructs a dummy key with the first byte set to all one bits 
(hexadecimal FF) and adds the block number in the first byte following the key. 
When a dummy block is written, a complete block is written from the area 
immediately following the area address; therefore, the area address pius the value 
specified in the BLKSIZE operand must be within the area allocated to the program 
writing the dummy blocks. 


length —symbol, decimal digit, absexp, (2-12), or ‘S’ 
The length operand is used only when undefined-length (3ECFM=VU) blocks are 
being written. The operand specifies the length of the block, in bytes, up toa 
maximum of 32,760. If ‘S’ is coded, it specifies that the system is to use the length in 
the block size (DCBBLKSI) field of the data control block as the length of the block 
to be written. 


If the Jength operand is omitted for format-U records, no error indication is given 
when the program is assembled, but the problem program must insert a length into the 
data event control block before the WRITE is issued. 


next address —A-Type Address or (2-12) | 
The next address operand specifies the address of the area where the system places 
the relative track address of the next record to be written. Next address feedback can 
be requested only when variable-length spanned records are used. 


Note: When variable-length spanned records are used (RECFM=VS and BFTEK=R are 
specified in the data control block), the system writes capacity records (RO) 
automatically in the following cases: 


e When a record spans a track. 


« When the record cannot be written completely on the current volume. In this case, all 
capacity records of remaining tracks on the current volume are written; tracks not 
written for this reason are still counted in the search limit specified in the LIMCT 
operand of the data control block. 


e When the record written is the last record on the track, the remaining space on the 
track cannot hold more than eight bytes of data. 
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Completion Codes 


After the write has been scheduled and control has been returned to the user’s program, 
the three high-order bytes of register 15 are set to zero, the low-order byte contains one 
of the following return codes: 


Return 
Code 


04 


08 


0C 


Meaning 
Fixed-Length 
(SF or SD) 


Block will be written. 
(If the previous return 
code was 08, a block 
is written only if the 


DD statement specifies . 


secondary space 
allocation and 
sufficient space is 
available. 


Block will be written, 
followed by a capacity 
record. 


Block will be written, 
followed by capacity 
record. The next block 
requires secondary 
space allocation. 


Block will not be 
written; issue a 
CHECK macro 
instruction for the 
previous WRITE macro 
instruction, then 
reissue the WRITE 
macro instruction. 


Variable or Undefined-Length 


(SF or SFR) 


Block will be written. 
(If the previous return 
code was 08, a block 

is written only if the 
DD statement specifies 
secondary space 
allocation and 
sufficient space is 
available. 


Block was not written; 
write a capacity record 
(SZ) to describe the 
current track, then 
reissue. 


Block will not be 
written; issue a 
CHECK macro 
instruction for the 
previous WRITE macro 
instruction, then 
reissue the WRITE 
macro instruction. 


(SZ) 


Capacity record was 
written; another track 
is available. 


Capacity record was 
written. The next 

block requires secondary 
space allocation. This 
code is not issued if 

the WRITE SZ is the 
only WRITE macro 
instruction issued on 

a one-track secondary 
extent. 


Block will not be 
written; issue a 
CHECK macro 
instruction for the 
previous WRITE macro 
instruction, then 
reissue the WRITE 
macro instruction. 
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WRITE—List Form 


The list form of the WRITE macro instruction is used to construct a data management 
parameter list in the form of a data event control block (DECB). Refer to Appendix A 
for a description of the various fields in the DECB for each access method. 


The description of the standard form of the WRITE macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates the operands used for each access method as well as the meaning of ‘S’ when 
coded for the area address, length, and key address operands. For each access method, 
‘S’ can be coded only for those operands for which it can be coded in the standard form 
of the macro instruction. The format description below indicates the optional and 
required operands in the list form only. 


The list form of the WRITE macro instruction is written as follows: 


[ symbol | decb name 
» type 
sLdcb address | 
sL area address | ‘S’] 


sl length | ‘S’] 
sLkey address | ‘S’] 
sl block address | 

yl next address | 
MF=L 





dech name —symbol 

type —Code one of the types shown in the standard form 
dcb address——A-Type Address 

area address—A-Type Address or ‘S’ 

length —symbol, decimal digit, absexp, or ‘S’ 

key address —A-Type Address or ‘S’ 

block address —A-Type Address 

next address —A-Type Address 


=L—Coded as shown 
The MF=L operand specifies that the WRITE macro instruction is used to create a 
data event control block that will be referenced by an execute-form instruction. 
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WRITE—Execute Form 


A remote data management parameter list (data event control block) is used in, and can 
be modified by, the execute form of the WRITE macro instruction. The data event 
control block can be generated by the list form of either a READ or WRITE macro 
instruction. 


The description of the standard form of the WRITE macro instruction provides the 
explanation of the function of each operand. The description of the standard form also 
indicates the operands used for each access method, as well as the meaning of ‘S’ when 
coded for the area address, length, and key address operands. For each access method, 
‘S’ can be coded only for those operands for which it can be coded in the standard form 
of the macro instruction. The format description below indicates the optional and 
required operands in the execute form only. 


The execute form of the WRITE macro instruction is written as follows: 


dech address 

type 

sLdcb address | 

sl area address | ‘S’] 


ol length | ‘S’] 

aL key address | ‘S’] 
| block address | 

sL next address | 
MF=E 





decb address —RX-Type Address or (2-12) 

type —Code one of the types shown in the standard form 
dcb address —-RX-Type Address or (2-12) 

area address —RX-Type Address, (2-12), or ‘S’ 

length —symbol, decimal digit, absexp, (2-12), or ‘S’ 

key address —RX-Type Address, (2-12), or ‘S’ 

block address —RX-Type Address or (2-12) 

next address —RX-Type Address or (2-12) 


MF=E—Coded as shown 
The MF=E operand specifies that the execute form of the WRITE macro instruction 
is used, and an existing data event control block (specified in the decb address 
operand) is to be used by the access method. 
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XLATE—rTranslate to and from ASCH (BSAM and 
QSAM) 


The XLATE macro instruction is used to translate the data in an area in virtual storage 
from ASCII code to EBCDIC code or from EBCDIC code to ASCII code. 


The XLATE macro instruction is written as follows: 


area address 


»length 
| [,TO={A | Et] 





| area address —RX-Type Address, symbol, decimal digit, absexp, (2-12), or (1) 

| The area address operand specifies the address of the area that is to be translated. 

| Jength—symbol, decimal digit, absexp, (2-12), or (0) 
The length operand specifies the number of bytes to be translated. 

| TO={A|E} 
The TO operand specifies the type of translation that is requested. If this operand is 
omitted, E is assumed. The following describes the characters that can be specified: 


A 
Specifies that translation from EBCDIC code to ASCII code is requested. 


E 
Specifies that translation from ASCII code to EBCDIC code is requested. 
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APPENDIX A: STATUS INFORMATION 
FOLLOWING AN INPUT/OUTPUT OPERATION 


Following an input/output operation, the control program makes certain status 
information available to the problem program. This information is a 2-byte exception 
code, or a 16-byte field of standard status indicators, or both. 


Exception codes are provided in the data control block (QISAM), or in the data event 
control block (BISAM and BDAM). The data event control block is described below, 
and the exception code lies within the block as shown in the illustration for the data 
event control block. If a DCBD macro instruction is coded, the exception code in a data 
control block can be addressed as two 1-byte fields, DCBEXCD1 and DCBEXCD2. The 
exception codes can be interpreted by referring to Figures 1-3. 


Status indicators are available only to the error analysis routine designated by the 
SYNAD entry in the data control block. A pointer to the status indicators is provided 
either in the data event control block (BSAM, BPAM, and BDAM), or in register 0 
(QISAM and QSAM). The contents of registers on entry to the SYNAD routine are 
shown in Figures 4-6; the status indicators are shown in Figure 7. 


Data Event Control Block 


A data event control block is constructed as part of the expansion of READ and WRITE 
macro instructions and is used to pass parameters to the control program, help control 
the read or write operation, and receive indications of the success or failure of the 
operation. The data event control block is named by the READ or WRITE macro 
instruction, begins on a fullword boundary, and contains the information shown in the 
following illustration: 


Field Contents 


Offset From DECB 
Address (Bytes) BSAM and BPAM BISAM BDAM 
0 ECB ECB ECB! 
+4 Type Type Type 
+6 Length Length Length 
+8 DCB address DCB address DCB address 
+12 Area address Area address Area address 
+16 IOB address - Logical record IOB address 
address 
+20 - Key address Key address 
+24 | Exception code Block address 
(2 bytes) 
+28 Next address 


1Exception codes are returned in bytes 2 and 3 of the ECB by the control program. 


The event control block (ECB) is used by the control program to test for completion of 
| the read or write operation. The ECB is located in the first word of the DECB. 


The type, length, data control block address, area address, key address, block address, 
and next address information is taken from the operands of the macro instruction and 
placed in the DECB for use by the control program. For BISAM, exception codes are 
returned by the control program after the corresponding WAIT or CHECK macro 

| instruction is issued, as indicated in Figure 1. For BDAM, BSAM, BPAM, and QSAM, 
the control program provides a pointer to the IOB containing the status indicators shown 
in Figure 7. 
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Exception 


Code Bit 
in DECB READ WRITE Condition if On 
0 xX Type K Record not found 
1 x xX Record length check 
2 Type KN Space not found 
3 Type K Invalid request 
4 XxX Xx Uncorrectable I/O 
error 
5 x xX Unreachable block 
| 6 X Overflow record! 
7 Type KN Duplicate record 
8-15 8-15 Reserved for 
control program use 


and bit 0, 4, 5, or 7 is also on. 
Figure 1. Exception Code Bits—BISAM 


| 1The SYNAD routine is entered only if the CHECK macro is issued after the READ macro, 


Notes for Figure 1: 


Record Not Found: This condition is reported if the logical record with the specified key 
is not found in the data set, if the specified key is higher than the highest key in the 
highest level index, or if the record is not in either the prime area or the overflow area of 
the data set. 


Record Length Check: This condition is reported, for READ and update WRITE macro 
instructions, if an overriding length is specified and (1) the record format is blocked, (2) 
the record format is unblocked but the overriding length is greater than the length known 
to the control program, or (3) the record is fixed length and the overriding length does 
not agree with the length known to the control program. This condition is reported for 
the add WRITE macro instruction if an overriding length is specified. 


When blocked records are being updated, the control program must find the high key in 
the block in order to write the block. (The high key is not necessarily the same as the key 
supplied by the problem program.) The high key is needed for writing because the 
control unit for direct-access devices permits writing only if a search on equal ts satisfied; 
this search can be satisfied only with the high key in the block. If the user were permitted 
to specify an overriding length shorter than the block length, the high key might not be 
read; then, a subsequent write request could not be satisfied. In addition, failure to write 
a high key during update would make a subsequent update impossible. 


Space Not Found in Which to Add a Record: This condition is reported if no room exists 
in either the appropriate cylinder overflow area or the independent overflow area when a 
new record is to be added to the data set. The data set is not changed in any way in this 
situation. 


Invalid Request: This condition is reported for either of two reasons. First, if byte 25 of 
the data event control block indicates that this request is an update WRITE macro 
instruction corresponding to a READ (for update) macro instruction, but the 
input/output block (IOB) for the READ is not found in the update queue. This 
condition could be caused by the problem program altering the contents of byte 25 of the 
data event control block. Second, if a READ or WRITE macro instruction specifies 
dynamic buffering (that is, ‘S’ in the area address operand) but the DCBMACRF field 
of the data control block does not specify dynamic buffering. 


Uncorrectable Input/Output Error: This condition is reported if the control program’s 
error recovery procedures encounter an uncorrectable error in transferring data. 
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Exception Code 
Field 
DCBEXCD1 


DCBEXCD2 


3-7 


Unreachable Block: This condition is reported if an uncorrectable input/output error 
occurs while searching the indexes or following an overflow chain. It is also posted if the 
data field of an index record contains an improper address (that is, points to the wrong 
cylinder or track or is an invalid address). 


Overflow Record: This condition is reported if the record just read is an overflow record. 
(See the section on direct retrieval and update of an indexed sequential data set in 
OS/VS Data Management Services Guide for consideration during BISAM updating.) 


Duplicate Record Presented for Inclusion in the Data Set: This condition is reported if the 
new record to be added has the same key as a record in the data set. However, if the 
delete option was specified and the record in the data set is marked for deletion, this 
condition is not reported. Instead the new record replaces the existing record. 


If the record format is blocked and the relative key position is zero, the new record 
cannot replace an existing record that is of equal key and is marked for deletion. 


Notes for Figure 2: 


Record Not Found: This condition is reported if the logical record with the specified key 
is not found in the data set, if the specified key is higher than the highest key in the 
highest level index, or if the record is not in either the prime area or the overflow area of 
the data set. 


Invalid Actual Address for Lower Limit: This condition is reported if the specified lower 
limit address is outside the space allocated to the data set. 


Space Not Found in Which to Add a Record: This condition is reported if the space 
allocated to the data set is already filled. In the locate mode, a buffer segment address is 
not provided. In the move mode, data is not moved. 


Invalid Request: This condition is reported if (1) the data set is already being referred to 
sequentially by the problem program, (2) the buffer cannot contain the key and the data, 
or (3) the specified type is not also specified in the DCBMACRF field of the data 
control block. 
Code Set by 
CLOSE GET PUT PUTX  SETL Condition if On 
Type K Record Not Found 
Type I Invalid actual address for lower limit 
xX Space not found in which to add a record 
4 Invalid request 
X Uncorrectable input error 
xX xX x Uncorrectable output error 
xX xX Block could not be reached (input) 
x XxX Block could not be reached (update) 
x Sequence check 
xX Duplicate record 


x Data control block closed when error routine 
entered 


xX Overflow record! 
xX Incorrect record length 


Reserved for future use 


1The SYNAD routine is entered only if bit 4, 5, 6, or 7 of DCBEXCD1 is also on. 
Figure 2. Exception Code Bits—QISAM 
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Uncorrectable Input Error: This condition is reported if the control program’s error 
recovery procedures encounter an uncorrectable error when transferring a The block 
from secondary storage to an input buffer. The buffer address is placed in register 1, and 
the SYNAD routine is given control when a GET macro instruction is issued for the first 
logical record. 


Uncorrectable Output Error: This condition is reported if the control program’s error 
recovery procedures encounter an uncorrectable error when transferring a block from an 
output buffer to secondary storage. If the error is encountered during closing of the data 
control block, bit 2 of DCBEXCD2 is set to 1 and the SYNAD routine is given control 
immediately. Otherwise, control program action depends on whether load mode or scan 
mode is being used. 


If a data set is being created (load mode), the SYNAD routine is given control when the 
next PUT or CLOSE macro instruction is issued. In the case of a failure to write a data 
block, register 1 contains the address of the output buffer, and register 0 contains the 
address of a work area containing the first 16 bytes of the IOB; for other errors, the 
contents of register 1 are meaningless. After appropriate analysis, the SYNAD routine 
should close the data set or end the job step. If records are to be subsequently added to 
the data set using the queued indexed sequential access method (QISAM), the job step 
should be terminated by issuing an ABEND macro instruction. (ABEND closes all open 
data sets. However, an ISAM data set is only partially closed, and it can be reopened in a 
later job to add additional records by using QISAM). Subsequent execution of a PUT 
macro instruction would cause reentry to the SYNAD routine, since an attempt to 
continue loading the data set would produce unpredictable results. 


If a data set is being processed (scan mode), the address of the output buffer in error is 
placed in register 1, the address of a work area containing the first 16 bytes of the IOB is 
placed in register 0, and the SYNAD routine is given control when the next GET macro 
instruction is issued. Buffer scheduling is suspended until the next GET macro instruction 
is reissued. 


Block Could Not be Reached (Input): This condition is reported if the control program’s 
error recovery procedures encounter an uncorrectable error in searching an index or 
overflow chain. The SYNAD routine is given control when a GET macro instruction is 
issued for the first logical record of the unreachable block. 


Block Could Not be Reached (Output): This condition is reported if the control program’s 
error recovery procedures encounter an uncorrectable error in searching an index or 
overflow chain. 


If the error is encountered during closing of the data control block, bit 2 of DCBEXCD2 
is set to 1 and the SYNAD routine is given control immediately. Otherwise, the SYNAD 
routine is given control when the next GET macro instruction is issued. 


Sequence Check: This condition is reported if a PUT macro instruction refers to a record 
whose key has a smaller numerical value than the key of the record previously referred to 
by a PUT macro instruction. The SYNAD routine is given control immediately; the 
record is not transferred to secondary storage. 


Duplicate Record: This condition is reported if a PUT macro instruction refers to a record 
whose key duplicates that of the record previously referred to by a PUT macro 
instruction. The SYNAD routine is given control immediately; the record is not 
transferred to secondary storage. 


Data Control Block Closed When Error Routine Entered: This condition is reported if the 
control program’s error recovery procedures encounter an uncorrectable output error 
during closing of the data control block. Bit 5 or 7 of DCBEXCD1 is set to 1, and the 
SYNAD routine is immediately given control. After appropriate analysis, the SYNAD 
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routine must branch to the address in return register 14 so that the control program can 
finish closing the data control block. 


Overflow Record: This condition is reported if the input record is an overflow record. 


Incorrect Record Length: This condition is reported if the length of the record as 
specified in the record-descriptor word (RDW) is larger than the value in the 
DCBLRECL field of the data control block. 


Exception 
Code Bit READ WRITE — Condition if On 
0 Xx xX Record not found 
1 X xX Record length check 
2 X Space not found 
3 xX X Invalid request—see bits 9-15 
4 xX xX Uncorrectable I/O error 
5 X Xx End of data 
6 X X Uncorrectable error 
7 Type X Not read with exclusive control 
8 Not used 
9 X WRITE to input data set 
10 X X Extended search with DCBLIMCT=0 
11 X xX Block or track requested was outside data set 
12 xX Tried to write capacity record 
13 xX xX Specified key as search argument when KEYLEN=0 or no 
key address supplied 
14 xX X Request for options not in data control block 
15 xX Attempt to add fixed-length record with key beginning 


with hexadecimal FF 


Figure 3. Exception Code Bits—BDAM 





Notes for Figure 3: 


Record Not Found: This condition is reported if the search argument is not found in the 
data set. 


Record Length Check: This condition occurs for READ and WRITE (update) and 
WRITE (add). For WRITE (update) variable-length records only, the length in the BDW 
does not match the length of the record to be updated. For all remaining READ and 
WRITE (update) conditions the BLKSIZE, when ‘S’ is specified in the READ or 
‘WRITE macro, or the length given with these macros does not agree with the actual 
length of the record. For WRITE (add), fixed-length records, the BLKSIZE, when ‘S’ is 
specified in the WRITE macro, or the length given with this macro does not agree with 
the actual length of the record. For WRITE (add), all other conditions, no error can 
occur. 


Space Not Found in Which to Add a Record: This condition occurs if either, there is no 
dummy record when adding an F-format record, or there is no space available when 
adding a V or U-format record. | 
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Invalid Request: Occurs whenever one of the following bits are set to one: 


Bit Meaning 


9 A WRITE was attempted for an input data set. 
10 An extended search was requested, but LIMCT was zero. 
11 The relative block or relative track requested was not in the data set. 
12 Writing a capacity record (RO) was attempted. 
13 A READ or WRITE with key was attempted, but either KEYLEN equaled zero or the key 
address was not supplied. 
14 The READ or WRITE macro options conflict with the OPTCD or MACRF parameters. 
15 A WRITE (add) with fixed-length was attempted with the key beginning with X‘FF’. 


Uncorrectable Input/Output Error: This condition is reported if the control program’s 
error recovery procedures encounter an uncorrectable error in transferring data between 
real and secondary storage. | 


End of Data: This only occurs as a result of a READ (type DI, DIF, or DIX) when the 
record requested is an end-of-data record. | 


Uncorrectable error: Same conditions as for bit 4. 


Not Read With Exclusive Control: A WRITE, type DIX or DKX, has occurred for which 
there is no previous corresponding READ with exclusive control. 


Register Bits Meaning 


0 0-7 Not used. 

8-31 Address of a work area containing the first 16 bytes of the IOB (after an 
uncorrectable input/output error caused by a GET, PUT, or PUTX macro 
instruction; original contents destroyed in other cases). If the error condition was 
detected before I/O was started, register 0 contains all zeros. 


l 0-7 Not used. 
8-31 Address of the buffer containing the error record (after an uncorrectable 
input/output error caused by a GET, PUT, or PUTX macro instruction while 
attempting to read or write a data record; in other cases this register contains 0). 


2-13 0-31 Contents that existed before the macro instruction was issued. 


14 0-7 Not used. 

8-31 Return address. This address is either an address in the control program’s Close 
routine (bit 2 of DCBEXCD72 is on), or the address of the instruction following the 
expansion of the macro instruction that caused the SYNAD routine to be given 
control (bit 2 of DCBEXCD72 is off). 


15 0-7 Not used. 
8-31 Address of the SYNAD routine. 


Figure 4. Register Contents on Entry to SYNAD Routine—QISAM 


Register Bits Meaning 


0 0-7 Not used. 
8-31 Address of the first IOB sense byte. (Sense information is valid only when associated 
with a unit check condition.) 


1 0-7 Not used. 
8-31 Address of the DECB. 
2-13 0-31 Contents that existed before the macro instruction was issued. 
14 0-7 Not used. 
8-31 Return address. 
15 0-7 Not used. 


8-31 Address of the SYNAD routine. 
Figure 5. Register Contents on Entry to SYNAD Routine—BISAM 
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Register Bits 


8-31 


N —_ 


5 


6 
7 
8-31 


2-13 0-31 


14 0-7 
8-31 


15 0-7 
8-31 


Meaning 


Value to be added to the status indicators address to provide the address of the first 
CCW (QSAM only). 

Address of the associated data event control block for BDAM, BPAM, and BSAM; 
address of the status indicators shown in Figure 7 for QSAM. 


Bit is on for error caused by input operation. 

Bit is on for error caused by output operation. 

Bit is on for error caused by BSP, CNTRL, or POINT macro instruction (BPAM 
AND BSAM only). 

Bit is on if error occurred during update of existing record or if error did not prevent 
reading of the record. Bit is off if error occurred during creation of a new record or 
if error prevented reading of the record. 

Bit is on if the request was invalid. The status indicators pointed to in the data event 
control block are not present (BDAM, BPAM, and BSAM only). 

Bit is on if an invalid character was found in paper tape conversion (BSAM and 
QSAM only). a 

Bit is on for a hardware error (BDAM only). 

Bit is on if no space was found for the record (BDAM only). 

Address of the associated data control block. 


Contents that existed before the macro instruction was issued. 


Not used. 
Return address. 


Not used. 
Address of the error analysis routine. 


Figure 6. Register Contents on Entry to SYNAD Routine-—BDAM, BPAM, BSAM, and QSAM 
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Offset From 


IOB Address 
Byte Bit Meaning Name 
+2 0 Command reject Sense byte 1 
1 Intervention required 
2 Bus-out check 
3 Equipment check 
4 Data check 
5 Overrun 
6,7 Device-dependent information; 
refer to the appropriate device 
manual 
+3 0-7 Device-dependent information; Sense byte 2 
refer to the appropriate device 
manual 


The following bytes make up the low-order seven bytes of 
the channel status word: 


Command address 


Attention Status byte 1 
Status modifier (Unit) 
Control unit end 

Busy 

Channel end 

Device end 

Unit check—must be on for 

sense bytes to be meaningful 

Unit exception 


+9 
+12 


vA bh WN = © 


+13 Program-controlled interrupt Status byte 2 
Incorrect length (Channel) 
Program check 

Protection check 

Channel data check 

Channel control check 

Interface control check 


Chaining check 
+14 — Count field (2 bytes) 
Figure 7. Status Indicators for the SYNAD Routine—-BDAM, BPAM, BSAM, and QSAM 


UA uUAwWN KO ~~] 





Note: If the sense bytes are X“10FE’, the control program has set them to this invalid 
combination because sense bytes could not be obtained from the device due to 
reoccurrence of unit checks. 
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APPENDIX B: DATA MANAGEMENT MACRO 
INSTRUCTIONS AVAILABLE BY ACCESS 


METHOD 


Macro Instruction 


BLDL 

BSP 

BUILD 
BUILDRCD 


CHECK 
CHKPT 
CLOSE 

CNTRL 


DCB 
DCBD 


ESETL 


FEOV 
FIND 
FREEBUF 
FREEDBUF 
FREEPOOL 


GET 
GETBUF 
GETPOOL 


NOTE 
OPEN 


PDAB 
PDABD 
POINT 
PRTOV 
PUT 
PUTX 


READ 
RELEX 
RELSE 


SETL 
SETPRT 
STOW 
SYNADAF 
SYNADRLS 


TRUNC 


WAIT 
WRITE 


XLATE 


BDAM BISAM BPAM BSAM QISAM QSAM 


Xx 
xX 
Xx x xX X X Xx 
X 
xX xX X X 
X X X X x X 
Xx Xx D4 xX X xX 
xX D4 
xX xX X X X xX 
X Xx X xX xX xX 
X 
X XxX 
X 
xX xX xX xX 
X xX 
xX xX X xX xX x 
xX xX 
X xX X XxX 
xX xX xX X X X 
X xX 
Xx xX X X X x 
xX 
xX 
X x 
Xx xX 
xX Xx 
X xX 
X xX xX x 
X 
xX Xx 
X 
xX X 
x 
xX xX X xX X 4 
x X xX XxX X xX 
xX 
X »,4 xX xX 
X X X xX 
X xX 
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APPENDIX C: DEVICE CAPACITIES 


The following information provides a guide to coding the block size (BLKSIZE) and 
logical record length (LRECL) operands in the DCB macro instruction. These values can 
be used to determine the maximum block size and logical record length for a given 
device, and they can be used to determine the optimum blocking factor when records are 
to be blocked. 


Card Readers and Card Punches 


Format F, V, or U records are accepted by readers and punches but the logical record 
length for a card reader or card punch is fixed at 80 bytes. The logical record length for 
an IBM 2596 Card Reader is 96 bytes. If the optional control character is specified, the 
logical record length is 81 (the control character is not part of the data record). If card 
image mode is used, the buffer required to contain the data must be 160 bytes. 


Printers 
The following shows the record length that can be specified for the various printers. In 
some cases, two values are shown; the larger of the two values requires that an optional 
feature be installed on the printer being used. If the optional control character is 
specified to control spacing and skipping, the record length is specified as one greater 
than the actual data length (the control character is not part of the data record). 
1403 printer — 120 or 132 bytes 
1443 printer — 120 or 144 bytes 
3211 printer — 132 or 150 bytes 
1052 printer keyboard — 130 bytes (supported only by the EXCP access method) 
3210 printer keyboard — 130 bytes (supported only by the EXCP access method) 
3215 printer keyboard — 130 bytes (supported only by the EXCP access method) 
3525 card punch, 
print feature — 64bytes 
Paper-Tape Reader 
2671 paper tape—32,760 bytes 
Magnetic-Tape Units 
2400/3400 magnetic-tape units—32,760 
(7 tracks and 9 tracks) 
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Direct-Access Devices 
The following table shows the capacity of direct-access devices by track, cylinder, and 


total capacity in bytes. 
Device Vohune Maximum Block- Tracks/ Number of Total 
Type size/Track! Cylinder Cylinders Capacity! 2 
2305-1 Drum 14136 8 48 5,428,224 
2305-2 Drum 14660 8 96 11,258,880 
2314/2319 Disk 7294 20 200 29,176,000 
| 3330/3333 
(Model 1)3 Disk 13030 19 404 100,018,280 
3330/3333 
(Model 11) Disk 13030 19 808 200,036,560 
3340 Disk 8368 12 696 
(70-megabytes) 69,889,536 
348 


(35-megabytes) 34,944,768 

1 Capacity indicated in bytes (when RO is used by the IBM programming system). 
2Excluding alternate cylinders. 
3The Mass Storage System (MSS) virtual volumes assume the 

characteristics of the 3330/3333, Model 1. 
Each record written on a direct-access device requires some ‘device overhead.” The 
term device overhead means the space required by the device for address markers, count 
areas, gaps between the count, key, and data areas, and gaps between blocks. The 
following formulas can be used to compute the number of bytes required for each data 
block including the space required for device overhead. Note that any fraction of a byte 
must be ignored. For example, if the formula computation results in 15.644 bytes, 15 
bytes must be used to determine track capacity. 


Bytes Required by Each Data Block 


Device Track Blocks With Keys Blocks Without Keys 
Capacity Bi Bi 

2305-1 145681 6344+KL+DL 432+DL 

2305-2 148581 289+KL+DL 198+DL 
2314/2319 7294 146+((KL+DL)*534)/5122 101+(DL)534/5123 
3330/3333 

(Model 1)4 131651 1914+KL+DL 135+DL 
3330/3333 

(Model 11) 131651 191+KL+DL 135+DL 
3340 85351 242+KL+DL 167+DL 
Bi is any block on the track. 
DL is data length. 
KL is key length. 


1 This value is different from the maximum block size per track because the 
formula for the last block on the track includes an overhead for this device. 

2'The formula for the last block on the track is 45+KL+DL. 

3The formula for the last block on the track is DL. 

4The Mass Storage System (MSS) virtual volumes assume the characteristics 
of the 3330/3333, Model 1. 


When the track-overflow feature is being used or variable-length spanned records are 
written, the size of a data block or logical record can exceed the capacity of a single track 
on the direct-access device used. 


246 OS/VS Data Management Macro Instructions 


APPENDIX D: DCB EXIT LIST FORMAT AND 


CONTENTS 


The following shows the format and contents that must be supplied by the problem 
program when the EXLST operand is specified in a DCB macro instruction. The exit list 
must begin on a fullword boundary and each entry in the list requires one fullword. 


Hexadecimal 
Routine Type Code 
Inactive entry 00 
Input header label 01 
Output header label 02 
Input trailer label 03 
Output trailer label 04 
Data control block exit 05 
End-of-volume 06 
User totaling 0A 
Block count exit OB 
Defer input trailer OC 
label 
Defer nonstandard OD 
input trailer label 
FCB Image 10 
DCB ABEND exit 11 
QSAM parallel input | 12 
Last entry 80 


3-Byte Routine Address—Purpose 


Ignored; the entry is not active. 

Process a user input header label. 

Create a user output header label. 

Process a user input trailer label. 

Create a user output trailer label. 

Data control block exit routine. 
End-of-volume exit routine. 

Pointer to user's totaling area. 

Block count unequal exit routine. 

Defer processing of a user input trailer label 
from the end-of-data until the CLOSE macro 
instruction is issued. 

Defer processing a nonstandard input trailer 
label on magnetic tape unit from the 
end-of-data until the CLOSE macro instruction 
is issued (no exit routine address). 

Define an FCB image. 

Allow analysis of ABEND condition and select 
one of several options. 

Address of the PDAB for which this DCB 

is a member 

Last entry in list. A high-order bit can be 
specified with any of the above codes but must 
always be specified with the last entry. 


The list can be dynamically shortened during execution by setting the high-order bit of a 
word to a value of 1. An entry in the list can be made inactive dynamically by setting the 
high-order byte of the word to a value of hexadecimal 00 or 80. 


When control is passed to an exit routine, the general registers contain the following 


information: 
Register Contents 


0 Variable; the contents depend on the exit routine used. 

1 The three low-order bytes contain either the address of the DCB 
currently being processed or, when certain exits are taken, the 
address of the exit parameter list. These exits are: user-label 
exits (X‘01’-‘04’), deferred nonstandard input trailer exit 
(X‘0D’), and DCB ABEND exit (X‘11’). 


2-13 Contents prior to execution of the macro instruction. 
14 Return address (must not be altered by the exit routine). 
15 Address of the exit routine entry point. 


The conventions for saving and restoring registers are as follows: 


e The exit routine must preserve the contents of register 14. It need not preserve the 
contents of other registers. The control program restores registers 2-13 before 
returning control to the problem program. 


e The exit routine must not use the save area whose address is in register 13, because 
this area is used by the control program. If the exit routine calls another routine or 
issues supervisor or data management macro instructions, it must provide the address 


of a new save area in register 13. 
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For a detailed description of each exit list processing option, refer to OS/VS Data 
Management Services Guide. 
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APPENDIX E: CONTROL CHARACTERS 


Machine Code 


Each logical record, in all record formats, can contain an optional control character. This 
control character is used to control stacker selection on a card punch or card read punch, 
or it is used to control printer spacing and skipping. If a record containing an optional 
control character is directed to any other device, it is considered to be the first data byte, 
and it does not cause a control function to occur. 


In format-F and format-U records, the optional control character must be in the first 
byte of the logical record. 


In format-V records, the optional control character must be in the fifth byte of the 
logical record, immediately following the record descriptor word of the record. 


Two control character options are available. A control character option is selected by 
coding the appropriate character in the RECFM operand of the DCB macro instruction. 
If either option is specified in the data control block, a control character must be 
included in each record, and other spacing or stacker selection options also specified in 
the data control block are ignored. 


The record format field in the data control block indicates that the machine code control 
character has been placed in each logical record. If the record is written, the appropriate 
byte must contain the command code bit configuration specifying both the write and the 
desired carriage or stacker select operation. 


The machine code control characters for a printer are as follows: 


Print and Then Act Act Immediately—No Printing 
(Code in Hexadecimal) Action (Code in Hexadecimal) 

01 Print only (no space) 

09 Space | line OB 

11 Space 2 lines 13 

19 Space 3 lines 1B 

89 Skip to channel 1 8B 

91 Skip to channel 2 93 

99 Skip to channel 3 9B 

Al Skip to channel 4 A3 

A9 Skip to channel 5 AB 

Bl Skip to channel 6 B3 

B9 Skip to channel 7 BB 

Cl Skip to channel 8 C3 

C9 Skip to channel 9 CB 

D1 Skip to channel 10 D3 
D9 Skip to channel 11 DB 
El Skip to channel 12 E3 
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The machine code control characters for a card read punch device are as follows: 
Code in Hexadecimal Action 


01 Select stacker 1 
41 Select stacker 2 
81 Select stacker 3 


Other command codes for specific devices are contained in IBM System Reference 
Library publications describing the control units or devices. 


American National Standards Institute Control Characters 


In place of machine code, control characters defined by the American National Standards 
Institute (ANSI) can be specified. These characters must be represented in EBCDIC 
code. 


American National Standards Institute (ANSI) control characters are as follows: 
Code Action Before Printing a Line 


Space one line (blank code) 
Space two lines 
Space three lines 
Suppress space 
Skip to channel 1 
Skip to channel 2 
Skip to channel 3 
Skip to channel 4 
Skip to channel 5 
Skip to channel 6 
Skip to channel 7 
Skip to channel 8 
Skip to channel 9 
Skip to channel 10 
Skip to channel 11 
Skip to channel 12 


Code Action After Punching a Card 


V Select punch pocket 1 
WwW Select punch pocket 2 


These control characters include those defined by ANSI FORTRAN. If any other 
character is specified, it is interpreted as ‘b’ or V, depending on the device being used; no 
error indication is returned. 


QW>OMIDRUNUAWNHK+ ' Cot 
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APPENDIX F: DATA CONTROL BLOCK 
SYMBOLIC FIELD NAMES 


The following describes data control block fields that contain information which defines 
the data characteristics and device requirements for a data set. Each of the fields 
described shows the values that result from specifying various options in the DCB macro 
instruction. These fields can be referred to by the problem program through the use of a 
DCBD macro instruction which creates a dummy control section (DSECT) for the data 
control block. Fields that contain addresses are 4 bytes long and are aligned on a 
fullword boundary. If the problem program inserts an address into a field, the address 
must be inserted into the low-order 3 bytes of the field without changing the high-order 
byte. 


The contents of some fields in the data control block depend on the device and access 
method being used. A separate description is provided when the contents of the field are 
not common to all device types and access methods. 


Data Control Block—Common Fields 
Bytes and Field 


Offset Alignment Name Description 
26(1A) 1 DCBDSORG Data set organization. 
Code 
| ae IS Indexed sequential. 
ads. -Soves PS Physical sequential. 
7 eee DA Direct organization. 
see. “XK Reserved bits. 
sols PO Partitioned organization. 
ssel U Unmovable—the data set contains 
location-dependent information. 


40(28) 8 DCBDDNAM Eight byte name of the data definition 
| statement that defines the data set associated 
with this DCB. (Before DCB is opened.) 


40(28) 2 DCBTIOT (After DCB is opened.) Offset from the TIOT 
origin to the TIOELNGH field in the TIOT 
entry for the DD statement associated with 
this DCB. 


42(2A) 2 DCBMACRF This field may only be referenced after OPEN. 
It is common to all uses of the DCB and is 
created by moving the DCBMACR field into this 
area. 


45(2D) 3 DCBDEBA (After DCB is opened.) Address of the associated 
DEB. 


48(30) 1 DCBOFLGS Flags used by Open routine. 
ath wees OPEN has completed successfully. 
we dees Set to 1 by problem program to indicate 
concatenation of unlike attributes. 

..0. Set to 0 by an I/O support function when that 
function takes a user exit. It is set to 0 to 
inhibit other I/O support functions from 
processing this DCB. 

ele Set to 1 on return from the user exit to the 
I/O support function that took the exit. 
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Offset 


50(32) 


Bytes and 
Alignment 


ay 4 


Field 
Name 


DCBMACR 
(Before 
OPEN) 


Description 


Macro instruction reference before OPEN. 
Major macro instructions and various options 
associated with them. Used by the Open 
routine to determine access method. Used by 
the access method executors in conjunction 
with other parameters to determine which load 
modules are required. This field is moved to 
overlay part of DCBDDNAM at Open time and 
becomes the DCBMACRF field. 


This field is common to all uses of the DCB, 
but each access method must be referenced for 
its meaning. — 3 


Data Control Block—BPAM, BSAM, QSAM 


Offset 
20(14) 


21(15) 
24(18) 


32(20) 


32(20) 


33(21) 
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Bytes and 
Alignment 
1 


3 


Field 
Name 


DCBBUFNO 


DCBBUFCB 
DCBBUFL 


DCBBFALN 
«XX 
..10 
..01 


DCBBFTEK 
XXX 

.1.0 

.0.1 

.110 


.010 


» oe 
DCBEODAD 


} 
Description 


Number of buffers required for this data set. 
May range from 0 to a maximum of 255. 


Address of buffer pool control block. 


Length of buffer. May range from 0 to a 
maximum of 32,760. 


Buffer alignment: 

D Doubleword boundary. 

F Fullword not a doubleword boundary, 
coded in the DCB macro instruction. 


Buffering technique: 

Simple buffering. 

Exchange buffering. 

QSAM locate mode processing of spanned 
records: OPEN is to construct a record 
area if it automatically constructs buffers. 


R BSAM create BDAM processing of un- 
blocked spanned records: Software track 
overflow. OPEN forms a segment work 
area pool and stores the address of the 
segment work area control block in 
DCBECBW. However, WRITE uses a 
segment work area to write a record as 
one or more segments. 


>mn 


BSAM input processing of unblocked 
spanned records with keys: Record offset 
processing. READ reads one record 
segment into the record area. The first 
segment of a record is preceded in the 
record area by the key. Subsequent — 
segments are at an offset equal to the key 
length. | 


Reserved bit. 


End-of-data address. Address of a user- 
provided routine to handle end-of-data 
conditions. _ 7 


Offset 


36(24) 


37(25) 


42(2A) 


50(32) 


51(33) 


Bytes and 
Alignment 


j 


3 


2 


mp 


Field 
Name 


DCBRECFM 


00.. ..1. 
10.. 
01.. 
11.. 
ele 
seek 


DCBEXLST 


DCBMACRF 


DCBMACR 
(Before 
OPEN) 


Description 


Record format. 


Code 
Format-D record. 
Fixed record length. 
Variable record length. 
Undefined record length. 
Track overflow. 
Blocked records. May not occur with 
undefined (U). 
Fixed length record format: Standard 
blocks. (No truncated blocks or unfilled 
tracks are embedded in the data set.) 
Variable length record format: Spanned 
records. , 
A ANSI control character. 
M Machine control character. 

No control character. 
Key length (KEYLEN) was specified in the 
DCB macro instruction. This bit is inspected 
by the Open routine to prevent overriding a 
specification of KEYLEN=0 by a nonzero 
specification in the JFCB or data set label. 


~~ ane <ae 3 w) 


7 a] 


Exit list. Address of a user-provided exit 
list control block. 


Macro instruction reference after OPEN. 


Contents.and meaning are the same as those of 
the DCBMACR field in the foundation segment 
before OPEN. 


Major macro instructions and various options 
associated with them. Used by the Open 
routine to determine access method. Used by 
the access method executors in conjunction 
with other parameters to determine which load 
modules are required. 


Code 
BSAM—lInput 
Always zero for BSAM. 
R READ 
Reserved bits. 
POINT (which implies NOTE). 
CNTRL 


BSAM——Output 

Always zero for BSAM. 

WRITE 

Load mode BSAM (create BDAM data 
set). 

POINT (which implies NOTE). 
CNTRL 

BSAM create BDAM processing of 
unblocked spanned records, with 
BFTEKE=R specified: The user’s program 
has provided a segment work area pool 
and stored the address of the segment 
work area control’ block in DCBEOBW. 


ts a 


OQ 'v 
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Bytes and 
Offset Alignment 
50(32) 
51(33) 
50(32) 
51(33) 


Direct-Access Storage Devices Interface 


Bytes and 
Offset Alignment 
16(10) 1 
17(11) 1 

Magnetic Tape Interface 

Bytes and 
Offset Alignment 
16(10) 1 
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Field 
Name 


DCBKEYLE 
DCBDEVT 


0010 0110 
0010 O111 
0010 1000 
0010 1001 


0010 
0010 


1101 
1010 


Field 
Name 


DCBTRTCH 


0010 0011 
0011 1011 
0001 0011 
0010 1011 


Description 


QSAM—Input 

Always zero for QSAM. 
GET 

Always zero for QSAM. 
Move mode. 

Locate mode. 
Substitute mode. 
CNTRL 

Data mode. 


QSAM—Output 

Always zero for QSAM. 
PUT 

Always zero for QSAM. 
Move mode. 

Locate mode. 
Substitute mode. 
CNTRL 

Data mode. 


BPAM—lInput 

Always zero for BPAM. 

READ 

POINT (which implies NOTE). 
Reserved bits. 


BPAM—Output 

Always zero for BPAM. 
WRITE 

POINT (which implies NOTE). 
Reserved bits. 


me vpadrze v, padre a 


U<a> 


Description 
Key length of the data set. 
Device type. 


2305 Disk Storage Facility, Model 1. 
2305 Disk Storage Facility, Model 2. 
2314 Disk Storage Facility. 

3330 Disk Storage, Model 1, or 
Mass Storage System (MSS) 

virtual volume. 

3330 Disk Storage, Model 11. 


3340 Disk Storage. 

Description 

Tape recording technique for 7-track tape. 
Code 

E Even parity. 

5 BCD/EBCDIC translation. 

C Data conversion. 

ET Even parity and translation. 


Bytes and 
Offset Alignment 
17(11) 1 
18(12) me 

Paper Tape Interface 

Bytes and 
Offset Alignment 
16(10) 1 


17(11) if 


Card Reader, Card Punch Interface 


Bytes and 
Offset Alignment 
16(10) 1 


17(11) 1 


Field 


Name Description 
DCBDEVT Device type. 
1000 0001 2400 series magnetic tape unit (7-track or 
9-track). 
DCBDEN Tape density—2400 series magnetic tape units. 
Code 7-tracks 9.tracks 
0000 0011 0 200 BPI — 
0100 0011 1 556 BPI — 
1000 0011 2 800 BPI 800 BPI 
1100 0011 3 — 1600 BPI 
4 6250 BPI 
Field 
Name Description 
DCBCODE Paper tape code being used. The appropriate 
translate table is made available. 
Code 
1000 0000 N No conversion 
0100 0000 I IBM BCD 
0010 0000 F Friden 
0001 0000 B Burroughs 
0000 1000 C National Cash Register 
0000 0100 A ASCII (8-track) 
0000 0010 T Teletype! 
DCBDEVT Device type. 
0101 0000 2671 Paper Tape Reader. 
Field 
Name Description 
DCBMODE,DCBSTACK 
Code 
XXXX Mode of operation for 1442 Card Read 
Punch. 
1000 .... C Column binary mode. 
0100 .... E EBCDIC mode. 
XXXX Stacker selection. 
0001 1 Stacker 1. 
0010 2 Stacker 2. 
DCBDEVT Device type. 
0100 0011 1442 Card Read Punch 
0100 0001 2540 Card Reader 
0100 0010 2540 Card Punch 
0100 0100 2501 Card Reader 
0100 0101 2520 Card Read Punch 
0100 0110 3505 Card Reader 
0100 1100 3525 Card Punch 


1Trademark of Teletype Corporation. 
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Printer Interface 


Bytes and Field 
Offset Alignment Name 


16(10) 1 DCBPRTSP 


0000 0001 
0000 1001 
0001 0001 
0001 1001 


DCBDEVT 


Byte 1 

0100 1000 
0100 1001 
0100 1010 


1711) Z 


Byte 2 
0010 0000 
0001 0000 


Access Method Interface 


BSAM, BPAM Interface 
Bytes and Field 
Offset Alignment Name 
52(34) 1 DCBOPTCD 
lias 
mn be 
sal 
re | 
elas 
Gedy 
| Fee 
waeX 
57(39) 3 DCBSYNAD 
62(3E) ys DCBBLKSI 
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Description 


Number indicating normal printer spacing. 


Code 

0 No spacing. 

1 Space one line. 

2 Space two lines. 
3 Space three lines. 


Device type. 


1403 Printer 
3211 Printer 
1443 Printer 


Test-for-printer-overflow mask (PRTOV 
mask). If printer overflow is to be 

tested for, the PRTOV macro instruction 
sets the mask as follows: 


Code 

9 Test for channel 9 overflow. 

12 Test for channel 12 overflow. 

Description 

Option codes. 

Code 

WwW Write-validity check (DASD). 

U Allow a data check caused by an invalid 
character. (1403 printer with UCS 
feature.) 

B Treat EOF and EOV labels as EOV labels 
which allows SL or AL tapes to be read 
out of order. (Magnetic tape.) 

C Chained scheduling. 

H Optical Reader: Hopper empty exit. 


Input Tape Files: Requests the 
testing for and bypassing of any 
embedded DOS checkpoint records 
encountered. (This code can only 
be specified in a JCL statement.) 

Z, Magnetic tape devices: Use reduced 
error recovery procedure. 

T BSAM only: user totaling. 

Q An ASCII data set is to be processed. 
Reserved bit. 


Address of user’s synchronous error routine to 
be entered when a permanent error occurs. 


Maximum block size. Maximum value: 32,760. 
For fixed-length blocked record format, it 
must be a multiple of the length given in 
DCBLRECL. For variable-length records, this 
must include the 4 byte block length field. 


QSAM Interface 


Offset 


72(48) 


80(50) 


81(51) 


82(52) 


Offset 
52(34) 


57(39) 


62(3E) 


80(50) 


81(51) 


Bytes and 
Alignment 


Bytes and 
Alignment 


3 


sed 


1 


oh. 


Field 
Name 


DCBNCP 


DCBUSASI/ 
DCBLBP 


Nis 


DCBBUFOF 
DCBLRECL 


Field 
Name 


DCBOPTCD 


elie 


oh; 
DCBSYNAD 


DCBBLKSI 


DCBUSASI/ 
DCBLBP 


= 


DCBBUFOF 


Description 


Number of chained programs. Number of 
READ or WRITE requests which may 

be issued prior to a CHECK. Maximum 
number: 99. 


ASCII tape. 
Block prefix. 


Block prefix is a four-byte field containing 
the block length. 


Block prefix length. 


Logical record length. For fixed-length blocked 
record format, the presence of DCBLRECL 
allows BSAM to read truncated records. For 
undefined records, this field contains block size. 


Description 
Option codes. 


Code 

Q An ASCII data set is to be processed. 
Same as DCBOPTQ. BSAM only. 

WwW Write-validity check (DASD). 


U Allow a data check for an invalid 
character (1403 with UCS). . 
B Treat EOF and EOV labels as EOV 


labels which allows SL or AL tapes 
to be read out of order (magnetic 


tape). 

C Chained scheduling using the Program 
Controlled Interruption. 

O Online correction. 


Input Tape Files: Requests the 
testing for and bypassing of any 
embedded DOS checkpoint records 
encountered. (This code can only 
be specified in a JCL statement.) 


Z Magnetic tape devices. Use reduced 
error recovery procedure. 
T User totaling. 


Address of the user’s synchronous error routine 
to be entered when a permanent error occurs. 


Maximum block size. Maximum value: 32,760. 
For fixed-length blocked record format, it must 
be a multiple of DCBRECL. For variable- 

length records this must include the 4-byte 

block length field provided by the access method. 


ASCII tape. 
Block prefix. 


Block prefix is a four-byte field containing 
the block length. 


Block prefix length. 
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Bytes and Field 
Offset Alignment Name Description 


82(52) ane: DCBLRECL Format-F records: Record length. 
Format-U records: Block size. 
Format-V records — 
° Unspanned record format —- 
GET: PUTX; record length. 
PUT: Actual or maximum record length. 
° Spanned record format — 
Locate mode — 
- GET: Segment length. 
- PUT: Actual or minimum segment 
length. 
Logical record interface — 
- Before OPEN: Maximum logical record 
length. 
- After GET: Record length. 
- Before PUT: Actual or maximum record 
length. 
Move mode — 
- GET: Record length. 
- PUT: Actual or maximum record length. 
° Data mode, GET — 
Data records up to 32,752 bytes: Data 
length. 
Data records exceeding 32,752 bytes: 
- Before OPEN: X°8000’ 
- After OPEN: Data length. 


° Output mode, PUTX (output data set): 
Segment length. | 
84(54) 1 DCBEROPT Error option. Disposition of permanent errors 


if the user returns from a synchronous error 
exit (DCBSYNAD), or if the user has no 
synchronous error exit. 


100. .... ACC: Accept. 
010. .... SKP: Skip. 
O01. .... ABE: Abnormal end of task. 
weX XXXX Reserved bits. 
85(55) 3 DCBCNTRA Address of CNTRL module. 
88(58) 2 Reserved. 
90(5A) Z DCBPRECL Block length, maximum block length or 
data length. 
92(5C) 4 DCBEOB Address of end of block module. 
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Data Control Block——-ISAM 


Bytes and 
Offset Alignment 
16(10) 1 
17(11) | 
20(14) 1 
21(15) 3 
24(18) 2 
32(20) 1 
33(21) 3 
36(24) 1 
37(25) 3 
42(2A) wake 


Field 
Name 


DCBKEYLE 
DCBDEVT 


0000 0110 
0000 0111 
0000 1000 


0000 1001 


0000 1101 
0000 1010 


DCBBUFNO 


DCBBUFCB 
DCBBUFL 
DCBBFALN 


XX 
..10 
..01 


11 
DCBEODAD 
DCBRECFM 


10.. 
10.. 
11.. 
son's 
| 


DCBEXLST 
DCBMACRF 


Description 
Key length. 
Device type. 


2305 Disk Storage Facility, Model 1. 
2305 Disk Storage Facility, Model 2. 
2314 Disk Storage Facility. 

3330 Disk Storage, Model 1, or 
Mass Storage System (MSS) 

virtual volume. 

3330 Disk Storage, Model 11. 

3340 Disk Storage. 


Number of buffers required for this data set: 
0-255. 


Address of buffer pool control block. 
Length of buffer: 0- 32,760. 


Code 
Buffer alignment: 

D Doubleword boundary. 

F Fullword not a doubleword boundary, 
coded in the DCB macro instruction. 


F Fullword not a doubleword boundary, 
coded in the DD statement. 


Address of a user-provided routine to handle 
end-of-data conditions. 


Record format. 


Code | 

Fixed length records. 

Variable length records. 

Undefined length records. 

Track overflow. 

Blocked records. May not occur with 
undefined (U). 

Standard records. No truncated blocks or 
unfilled tracks are embedded in the 

data set. 

ANSI control character. 

Machine control character. 

No control character. 

Key length (KEYLEN) was specified in 
the DCB macro instruction; this bit is 
inspected by the Open routine to prevent 
overriding a specification of KEYLEN=0 by 
a nonzero specification in the JFCB or 
data set label. 


OM Woden 


=> 


Exit list. Address of a user-provided list. 
Macro instruction reference after OPEN: 


Contents and meaning are the same as those 
of the DCBMACR field before OPEN. 
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Offset 


50(32) 


50(32) 


51(33) 


50(32) 


51(33) 


52(34) 


53(35) 


54(36) 


55(37) 
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Bytes and 
Alignment 


ay. 


Field 
Name 


DCBMACR 


DCBOPTCD 


DCBCYLOF 


Description 


Macro instruction reference before OPEN: 
specifies the major macro instructions and 
various options associated with them. Used 

by the Open routine to determine access method. 
Used by the access method executors in 
conjunction with other parameters to determine 
which load modules are required. 


Code 

BISAM 

Always zero for BISAM. 
READ 

Dynamic buffering. 
CHECK 

Reserved bit. 


BISAM 
Always zero for BISAM. 
W WRITE 


QISAM 

Always zero for QISAM. 
GET 

Move mode of GET. 
Locate mode for GET. 
Reserved bits. 


QISAM 
S SETL 
P PUT or PUTX. 

Always zero for QISAM. 
M Move mode of PUT. 
L Locate mode of PUT. 
U Update in place (PUTX). 
K 
I 


ANP 


rZza 


SETL by key. 
SETL by ID. 


Option codes: 


Code 

WwW Write-validity check. 

U Full-track index write. 

M Master indexes. 

I Independent overflow area. 

Y Cylinder overflow area. 

L Delete option. 

R Reorganization criteria. 
Reserved bit. 


Extension of the DCBMACRF field for ISAM. 


Code 
Reserved bits. 


U Update for read. 
U Update type of write. 
A Add type of write. 


Number of tracks that determines the 
development of a master index. 
Maximum permissible value: 99. 


The number of tracks to be reserved on each 
prime data cylinder for records that overflow 
from other tracks on that cylinder. Refer to 
the section on allocating space for an ISAM 
data set in OS/VS Data Management Services 
Guide. to determine how to calculate the 
maximum number. 


Offset 


56(38) 
60(3C) 


62(3E) 
64(40) 


68(44) 


70(46) 
72(48) 


73(49) 


80(50) 


81(51) 


82(52) 


197(C5) 


Bytes and 
Alignment 


4 


1 


ee 


a 


Field 
Name 


DCBSYNAD 
DCBRKP 


DCBBLKSI 
DCBMSWA 
DCBSMSI 


DCBSMSW 
DCBNCP 


DCBMSHI 


DCBEXCD1 


DCBEXCD2 


-XXX 


DCBLRECL 


DCBOVDEV 


0010 0110 
0010 0111 
0010 1000 
0010 1001 


0010 1101 
0010 1010 


Description 


Address of user’s synchronous error routine 
to be entered when uncorrectable errors are 
detected in processing data records. 


Relative position of the first byte of the key 
within each logical record. Maximum permissible 
value: logical record length minus key length. 


Block size. 


Address of the storage work area reserved for 
use by the control program when new records 
are being added to an existing data set. 


Number of bytes in area reserved to hold the 
highest level index. 


Number of bytes in work area used by control 
program when new records are being added to 
the data set. 


Number of copies of the READ-WRITE (type K) 
channel programs that are to be established 
for this data control block (99 maximum). 


Address of the storage area holding the 
highest level index. 


First byte in which exceptional conditions 
detected in processing data records are 
reported to the user. 


Lower key limit not found. 

Invalid device address for lower limit. 
Space not found. 

Invalid request. 

Uncorrectable input error. 
Uncorrectable output error. 

Block could not. be reached (input). 
Block could not be reached (update). 


Second byte in which exceptional conditions 
detected in processing data records are 
reported to the user. 


Sequence check. 

Duplicate record. 

DCB closed when error was detected. 
Overflow record. 

PUT: length field of record larger than 
length indicated in DCBLRECL. 
Reserved bits. 


Logical record length for fixed-length record 
formats. Variable-length record formats: 
maximum logical record length or an actual 
logical record length changed dynamically 
by the user when creating the data set. 


Device type for independent overflow. 


2305 Disk Storage Facility, Model 1. 
2305 Disk Storage Facility, Model 2. 
2314 Disk Storage Facility. 

3330 Disk Storage, Model 1, or 
Mass Storage System (MSS) 

virtual volume. 

3330 Disk Storage, Model 11. 

3340 Disk Storage. 
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Data Control Block—BDAM 


Offset 
16(10) 
17(11) 


20(14) 


21(15) 


24(18) 
32(20) 


32(20) 


36(24) 
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Bytes and 
Alignment 


1 
3 


1 


Field 
Name 


DCBKEYLE 
DCBREL 


DCBBUFNO 


DCBBUFCB 


DCBBUFL 
DCBBFALN 


XX 
..10 
..0O1 


sold 


XX X.. 
DCBBFTEK 


=< 
ils 


DCBRECFM 


10.. 
01.. 
11.. 
sade 


soul 


* 
. 
« 
—_ 


Description 
Key length. 


Number of relative tracks or blocks in this 
data set. 


Number of buffers required for this data set. 
May range from 0 to 255. 


Address of buffer pool control block or of 
dynamic buffer pool control block. 


Length of buffer. May range from 0 to 32,760. 


Buffer alignment: 

Doubleword boundary. 

Fullword not a doubleword boundary, coded in 
the DCB macro instruction. 

Fullword not a doubleword boundary, coded in 
the DD statement. 

Reserved bits. 


Buffering technique. 

R Unblocked spanned records: 
Software track overflow. OPEN forms a 
segment work area pool. The number of 
segment work areas is determined by 
DCBBUFNO (OPEN stores the address of 
the segment work area control block 
in DCBDYNB) if dynamic buffering is not 
used or in the dynamic buffer pool 
control block (see DCBBUFCB) if 
dynamic buffering is used. WRITE uses 
a segment work area to write a record 
aS One or more segments. READ uses a 
segment work area to read a record that 
was written as one or more segments. 


Record format. 


Code 

Fixed record length. 
Variable record length. 
Undefined record length. 
Track overflow. 


Blocked (allowed only with V). 
Spanned (allowed only with V). 

Always zeros. 

Key length (KEYLEN) was specified in 
the DCB macro instruction. This bit 

is inspected by the Open routine to 
prevent overriding a specification of 
KEYLEN=0 by a nonzero specification 
in the JFCB or data set label. 


AmW Ac < 4 


Offset 
37(25) 


42(2A) 


50(32) 


50(32) 


51(33) 


52(34) 


56(38) 


62(3E) 
81(51) 


Bytes and 
Alignment 


Field 
Name 


DCBEXLST 


DCBMACRF 


DCBMACR 


Byte 1 


DCBOPTCD 


DCBSYNAD 


DCBBLKSI 
DCBLIMCT 


A= RA 


Description 


Exit list. Address of a user-provided exit 
list control block. 


Macro instruction reference after OPEN. 


Contents and meaning are the same as 
DCBMACR before OPEN. 


Macro instruction reference before OPEN: 
major macro instructions and various options 
associated with them that will be used. 


Code 

Always zero for BDAM. 

READ 

Key segment with READ. 

ID argument with READ. 

System provides area for READ (dynamic 
buffering). 

Read exclusive. 

CHECK macro instruction. 


a *K 


2) 


ode 

Always zero for BDAM. 

WRITE 

Key segment with WRITE. 

ID argument with WRITE. 
Reserved bit. 

Add type of WRITE. 

Unblocked spanned records, with 
BFTEK=R specified and no dynamic 
buffering: The user’s program 

has provided a segment work area 
pool and stored the address of 

the segment work area control 
block in DCBDYNB. 


Option codes: 


Code 

W Write-validity check. 
Track overflow. 

E Extended search. 

F Feedback. 

A Actual addressing. 
Dynamic buffering. 
Read exclusive. 

R Relative block addressing. 


Address of SYNAD (synchronous error) 
routine. 


> 


Maximum block size. 


Number of tracks or number of relative blocks 
to be searched (extended search option). 


Appendix F: Data Control Block Symbolic Field Names 263 


APPENDIX G: EVENT CONTROL BLOCK 


The event control block is used for communications between the various components of 
the system and between problem programs and the system. An event control block is the 
subject of WAIT and POST macro instructions. The following illustration shows the 
format of the event control block; a description of its fields follows the illustration. 





Bytes and 
Offset Alignment Code 


0 1 10xx 
O1xx 


0111 
0100 


0100 


0100 


0100 


0100 


0100 


0100 


0101 


Bit 


XXXX . 


XXXX 


1111 


0001 


0010 


0011 


0100 


1000 


1011 


1111 


Hex. 


Dig. 
80 
40 


TF 


Al 


42 


43 


48 


4B 


4F 


50 


Description 
W-——Waiting for completion of an event. 
C—-The event has completed. 


One of the following completion codes 
will appear at the completion of a 
channel program: 


Access Methods Other Than BTAM 


Channel program has terminated without 
error. (CSW contents useful.) 


Channel program has terminated with 
permanent error. (CSW contents useful.) 


Channel program has terminated because 
a direct access extent address has been 
violated. (CSW contents do not apply.) 


I/O ABEND condition occurred 
while loading the error recovery 
routine. (CSW contents do 

not apply.) 


Channel program has been intercepted 
because of permanent error associated 
with device end for previous request. 
You may reissue the intercepted 
request. (CSW contents do not apply.) 


Request element for channel program 
has been made available after it has 
been purged. (CSW contents do no apply.) 


One of the following errors occurred 
during tape error recovery processing. 


« The CSW command address in 
the IOB was zeros. 

e An unexpected load point was 
encountered. 
(CSW contents do not apply in 
either case.) 


Error recovery routines have been 
entered because of direct access error 

but are unable to read home addresses 

or record 0. (CSW contents do not apply.) 


Channel program terminated with error. 
Input block was a DOS-embedded checkpoint 
record. (CSW contents do not apply.) 
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APPENDIX H: PDABD SYMBOLIC FIELD NAMES 


The following describes PDABD fields of the dummy control section generated by the 
PDABD macro instruction. Included are the names, attributes, and descriptions of the 
dummy control section. The use of any of the symbolic names provided by the dummy 
section should be preceded by a USING instruction specifying IHAPDAB and a dummy 
section base register containing the address of the actual parallel data access block. 


THAPDAB DSECT 


PDANODCB ODS H number of DCB addresses in list 
PDAMAXCB- ODS H maximum number of addresses allowed 
PDAGRTNA DS A address of parallel GET routine 
PDADCBAI DS F DCB address increment 

PDADCBLA DS A address of last DCB entry 

PDADCBEP DS A address of DCB entry last processed 
PDAECBIX DS F index to ECB list 

PDADCBAL EQU * start of DCB list 
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INDEX 


For additional information about any subject listed in this 
index, refer to the publications that are listed under the same 
subject in either OS/VSI Master Index, GC24-5104, or 
OS/VS2 Master Index, GC28-0693. 


A 


A-type address constant defined 21 
ABEND exit, DCB macro 
BDAM 65 
BISAM 71 
BPAM 78 
BSAM 94 
list format 247-248 
QISAM 104-105 
QSAM_ 123 
absexp defined 21 
absolute expression defined 21 
access methods 
general description 
BDAM 61 
BISAM 69 
BPAM 75 
BSAM 83 
QISAM 101 
QSAM 111 
macro instructions used with 243 
ACSMETH operand, SYNADAF macro 210 
actual device addressing (BDAM) 61,67 
adding data to a data set 
BDAM 66,219-220,225 
BISAM 71,221-222 
BPAM 223-224 
BSAM 223-224,225-226 
QISAM 171 
QSAM_ 173-174 
address constant, A-type 
defined 21 
address feedback 
current block position 177,220 
next block position 177,220 
address of buffers 
obtained from a pool 149 
returned to a pool 137 
addressing, types of (BDAM) 61,67 
aids, coding 17-19 
alias names in a directory 205-206 
alignment of buffers 
BDAM 62 
BISAM 70 
BPAM 76 
BSAM 85 
QISAM - 102 
QSAM 113 
American National Standards Institute 
(ANSD control characters 
BPAM 80 
BSAM 98 
defined 250 
QSAM 126 
ANSI 
(ee American National Standards Institute) 


argument, search 
BDAM 66 
QISAM 106 
ASCII data sets 
block prefix 
BSAM 87 
QSAM 116 
restriction 87,116 
block size 
BSAM 8&6 
QSAM 115 
buffer length 
BSAM 87 
QSAM 115 
on paper tape 
BSAM 90 
QSAM 118 
restriction on record format 
BSAM 98 
QSAM 126 
ASCII translation routines 
Check routine 39 
DCB option 
BSAM 96 
QSAM_ 125 
Get routine 145 
Put routine 173 
Write routine 223 
XLATE macro instruction 233 
associated data sets 
closing 49 
opening 155 
types of 
BSAM 92-93 
QSAM 120-121 
ATTACH macro, relationship with BLDL macro 27 
automatic buffer pool construction 
BDAM 61 
BISAM 69 
BPAM 75 
BSAM 83 
QISAM 101 
QSAM 111 
automatic checkpoint restart 41 
automatic volume switching (FEOV macro) 133 


B 


backspacing 

BSP macro 29 

CNTRL macro 57,58 
backward read 

open option 156 

read operation 183 
base registers for 

dummy sections 129 

macro instructions 22 
BCD 8-track paper tape code 

BSAM 90 

QSAM 118 
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BDAM (basic direct access method) 
general description 61 
macro instructions used with 243 
symbolic field names in DCB 262-263 
BFALN operand (DCB macro) 
BDAM 62 
BISAM 70 
BPAM 76 
BSAM 85 
QISAM 102 
QSAM 113 
BFTEK operand (DCB macro) 
BDAM 62-63 
BSAM 85-86 
QSAM 114 
BISAM (basic indexed sequential access method) 
general description 69 
macro instructions used with 243 
symbolic field names in DCB 259-261 
BLDL macro instruction 
description 27-28 
reason codes 28 
return codes 28 
used with FIND 135 
BLKSIZE operand (DCB macro) 
BDAM 63 
BPAM 76-77 
BSAM 86 
QISAM. 102-103 
QSAM 114-115 
block 
backspacing by 29 
count exit 
BSAM 94 
list format 247 
QSAM_ 123 
data control 61-127 
data event control 235 
descriptor word, relationship with 
BLKSIZE operand 77,86,103 
BUFOFF operand 87,116 
LRECL operand 95,105 
event control 236,265 
position feedback 177-179,219-220 
positioning with POINT 167-168 
prefix 
(see also BUFOFF operand) 
effect on buffer length 87,115 
effect on data alignment 85,113 
reading 177-185 
size 
(see BLKSIZE operand) 
writing 219-226 
block size for SYSOUT data sets 
(see also BLKSIZE operand) 
BSAM 86 
QSAM 114 
blocking 
data checks (UCS printer) 198 
records 
BDAM 61,68 
BPAM 75,80 
BSAM 83,98 
QISAM 101,108 
QSAM 111,126 
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boundary alignment 
(see BFALN operand) 
BPAM (basic partitioned access method) 
general description 75 
macro instructions used with 243 
symbolic field names for DCB 252-257 
BSAM (basic sequential access method) 
general description 83 
macro instructions used with 243 
symbolic field names for DCB 252-257 
BSP macro instruction 
description 29 
reason codes 29 
return codes 29 
BUFCB operand (DCB macro) 
BDAM 63 
BISAM 70 
BPAM 77 
BSAM 86-87 
QISAM 103 
QSAM 115 
relationship to 
GETBUF macro 149 
GETPOOL macro 151 
buffer 
alignment 
(see BFALN operand) 
control 
automatic 143-147,171-174 
dynamic 139 
using FREEBUF macro 137 
using FREEDBUF macro 139 
using GETBUF macro 149 
using RELSE macro 193 
forms control 
using SETPRT macro 197 
length 
(see also BUFL operand) 
BUILD macro 31-32 
BUILDRCD macro 33-34 
for card image mode 87,115 
for ASCII data sets 87,115 
GETPOOL macro 151-152 
message format (SYNADAF macro) 212 
pool construction 
(see also BUFCB operand) 
automatic 
(see BUFNO operand) 
using BUILD macro 31 
using BUILDRCD macro 33 
using GETPOOL macro 151 
releasing of 
using FREEBUF macro 137 
using FREEDBUF macro 139 
using FREEPOOL macro 141 
using RELSE macro 193 
using SYNADRLS macro 213 
specifying number (see BUFNO operand) 
buffering, types of 
automatic 143-147,171-174 
dynamic 139 
exchange 114 


buffering, types of (continued) 
problem program controlled 
BDAM 64 
BISAM 70-71 
BPAM 77 
BSAM 87 
simple 114 
variable-length spanned record 
BDAM 64 
QSAM 114 
using BUILDRCD macro 33 
BUFL operand (DCB macro) 
BDAM 63-64 
BISAM 70 
BPAM 77 
BSAM 87 
QISAM 103 
QSAM 115 
BUFNO operand (DCB macro) 
BDAM 64 
BISAM 70-71 
BPAM 77 
BSAM 87 
QISAM 103-104 
QSAM 115-116 
relationship to NCP operand 72 
BUFOFF operand (DCB macro) 
BSAM 87-88 
QSAM 116 
BUILD macro instruction 
description 31-32 
relationship to 
BFALN operand 62 
BUFCB operand 63 
BUFL operand 64 
BUENO operand 64 
BUILDRCD macro instruction 
description 
execute form 37 
list form 35 
standard form 33-34 
relationship to 
buffer length 
(see BUFL operand) 
GET macro 146 
number of buffers 
(see BUFNO operand) 
PUT macro 174 
TRUNC macro 215 
Burroughs 7-track paper tape code 
BSAM 90 
QSAM 118 


C 


CANCEL operand, CHKPT macro 42 
capacity record (RO) 
relationship with 
READ macro 178,179 
WRITE macro 219,225,226 
card 
code 
BSAM 91 
QSAM 119 
image mode 
buffer length required 87,115 
defined 91,119 


punch 91,119 
reader 91,119 
carriage 
control channel 
CNTRL macro 57-59 
PRTOV macro 169-170 
control characters 
ANSI 250 
CNTRL macro 57-59 
machine 249-250 
PRTOV macro 169-170 
chained scheduling option 
BPAM 80 
BSAM 96 
QSAM 124 
changing partitioned data set member name 205-207 
channel 
carriage control . 
(see carriage control channel) 
overflow 169-170 
programs, number of 
BISAM 72 
BPAM 79 
BSAM 96 
CHECK macro instruction 
description 39 
relationship to 
end of data(EODAD) 78,94 
MACREF operand 66 
number of read and write 
operations (NCP) 72,79,96 
POINT macro 168 
READ macro 177,181,183,185 
WRITE macro 219,221,223,225 
return of exception codes 236 
checking, write-validity 
BDAM 67 
BPAM 80 
BSAM 97 
QISAM 107 
QSAM 125 
checkpoint data set 41 
checkpoint records, embedded (DOS) 
CNTRL macro 57 
POINT macro 167 
CHKPT macro instruction 
execute form 47 
list form 45 
return codes 43 
standard form 41-43 
CLOSE macro instruction 
execute form 55 
list form 53 
relationship to 
BUILDRCD macro 34 
FREEPOOL macro 141 
POINT macro 167 
PUT macro 171,174 
SETL macro 195 
standard form 49-51 
TYPE=T (BSAM) 50-51 
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CNTRL macro instruction 
description 57-59 
restriction on use 29,57 
specified in MACRF operand (DCB macro) 
BSAM 95 
QSAM 123 
code 
card 
BSAM 91 
QSAM 119 
completion 
(see code, return) 
control character 
(see control characters) 
conversion 
ASCII to EBCDIC 39,145,233 
EBCDIC to ASCII 223,233 
paper tape 90,118 
XLATE macro 233 
exception 235-239 
return 
BLDL macro 28 
BSP macro 29 
CHKPT macro 43 
FIND macro 136 
RELEX macro 191 
SETPRT macro 199 
STOW macro 207 
SYNADAF macro 211 
SYNADRLS macro 213 
WRITE macro 227 
CODE operand (DCB macro) 
BSAM 90 
QSAM 118 
coding 
aids 17-19 
macro instructions 20-22 
registers as operands 21 
column, binary 
(see card image mode) 
eliminate mode, read 
BSAM 91,92 
QSAM_ 119,120 
completion codes 
BLDL macro 28 
BSP macro 29 
CHKPT macro 43 
FIND macro 136 
RELEX macro 191 
SETPRT macro 199 
STOW macro 207 
SYNADAF macro 211 
SYNADRLS macro 213 
WRITE macro 227 
completion testing of I/O operations 39,217-218 
concatenation 
input data sets (BPAM) 75 
condition, exception 235-239 
construct 
a buffer pool 
(see buffer pool construction) 
a data control block 
(see DCB macro instruction) 
a DECB (data event control block) 235 
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contents of registers on entry to 
exit list 247 
SYNAD 240-241 
control 
characters 249-250 
I/O device 57-59,169-170 
page format 169-170 
releasing 
buffer (FREEBUF macro) 137 
buffer pool (FREEPOOL macro) 141 
data block 191 
dynamically acquired buffer 139,220 
QSAM buffer (RELSE macro) 193 
requesting 
buffer (GETBUF macro) 149 
buffer pool (GETPOOL macro) 151-152 
data block 177,181,183,185 
control block 
buffer pool 
(see BUFCB operand) 
data 
(see DCB macro instruction) 
dataevent 235 
event 265 
control characters 
ANSI 250 
CNTRL macro 57-59 
machine 249-250 
PRTOV macro 169-170 
specifying for 
BPAM 80 
BSAM 98 
QSAM 126 
control section (CSECT) 
(see DCB macro instruction) 
count exit, block 
BSAM 94 
format list 247 
QSAM_ 123 
cylinder 
index 106 
overflow area 104 
CYLOFL operand 104 


D 


D-format records 
BSAM 98 
QSAM_ 126 
data, end of 
(see EODAD operand) 
data block 
exclusive control of 177 
locating with POINT macro 167-168 
release of exclusive control 191 
retrieval 143-147,177-185 
writing 171-175,219-227 
data checks 
blocking and unblocking 97,125,198 
restriction with CNTRL macro 57-59 
data control block 
completing 155 
construction 
(see DCB macro instruction) 
DCBBLKCT field 58 
DCBEXCDI1 field 235 


data control block (continued) 
DCBEXCD72 field 235 
DCBLRECL field 173 
DCBNCRHI field 72 
DCBOFLGS field 157,158 
description 
(see DCB macro instruction) 
dummy section for 129-130 
exit list 
(see EXLST operand) 
special options with BLDL macro 27-28 
symbolic references to 251-263 
data definition statement 
(see DD statement) 
data event control block 
construction 187,229 
description 235 
exception code 235-239 
modifying with execute form 189,231 
requirement with CHECK macro 39 
requirement with FREEDBUF macro 139 
data management parameter list 53,159 
data mode 
GET macro 124,146 
PUT macro 124,174 
data protection image (DPI) 
BSAM 91,93 
QSAM 119,121 
data set 
block size for SYSOUT 86,114 
closing 49-51 
connecting to 155-158 
disconnecting from 49-51 
disposition at close 50 
opening 155-158 
organization 
(see DSORG operand) 
temporary closing 50-51 
types 
(see access methods) 
data translation 
(see code conversion) 
data transmittal modes 
data 146,174 
locate 143,146,171,173-174 
move 143,146,171,174 
specified in DCB 106,124 
substitute 146,174 
DCB ABEND exit 
BDAM 65 
BISAM 71 
BPAM 78 
BSAM 94 
list format 247 
QISAM 104-105 
QSAM_ 123 
DCB macro instruction 
BDAM 61-68 
BISAM 69-73 
BPAM 75-81 
BSAM 83-99 
QISAM 101-109 
QSAM_ 111-127 
DCB operands 
description 
(see DCB macro instruction) 
symbolic names for 251-263 


DCBD macro instruction 
description 129-130 
DD statement, relationship to 
data control block 
(see DDNAME operand) 
NOTE macro 153 
OPEN macro 155-158 
_ POINT macro 167-168 
DDNAME operand (DCB macro) 
BDAM 64 
BISAM 71 
BPAM 77-78 
BSAM 88 
QISAM 104 
QSAM 116 
DEB validity checking 155 
deblocking records 
BDAM 61,68 
BPAM 75,80 
BSAM _ 83,98 
QISAM_ 101,108 
QSAM_ 111,126 
DECB 
(see data event control block) 
deferred checkpoint restart 41 
delete option 
description 107 
DEN operand (DCB macro) 
BSAM 89 
QSAM 117 
density, recording 
(see DEN operand) 
descriptor word 
block 
BPAM 77 
BSAM_ 86,87,95 
QISAM 103,105 
QSAM 116 
record 
BSAM 87,95 
QISAM 103,105 
QSAM 123 
segment 86,185 
DEVD operand (DCB macro) 
BSAM._ 88-93 
DCBD macro 130 
QSAM 116-121 
device addressing, types of (BDAM) 67 
device capacities 245-246 
device types in a dummy section 130 
direct-access storage device 
capacity 245-246 
considerations with 
BSP macro 29 
CHKPT macro 41 
CLOSE macro 49,50 
POINT macro 167-168 
interface in DCB 254 
direct data set 
(see BDAM) 
direct search option 
BSAM 97 
QSAM 125 
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directory, partitioned data set 
creation 75 
obtaining contents with BLDL 27-28 
operations performed by STOW macro 205-207 
search by FIND macro 135-136 
DISP option 
(see disposition option) 
disposition option 
CLOSE macro 50 
OPEN macro 156-157 
requirement for extending an 
ISAM data set 171 
DOS embedded checkpoint records, relationship with 
CNTRL macro 57 
POINT macro 167 
DOS/OS interchange feature, specifying 97,125 
doubleword alignment 
(see BFALN operand) 
DPI (data protection image), specifying 
for BSAM_ 91,93 
for QSAM 119,121 
DSECT for 
DCB symbolic names 251 
DSORG operand 
CHECK macro 39 
DCB macro 
BDAM 64-65 
BISAM 71 
BPAM 78 
BSAM 94 
DCBD macro 129-130 
QISAM 104 
QSAM_ 122 
dummy control section 
DCBD macro 129-130 
how used 251 
dummy data block (BDAM) 225-226 
dummy key 226 
dynamic buffering 
effect on buffer length 63,70 
effect on number of channel programs 72 
requesting in READ macro 178,181 
requesting in WRITE macro 220,221 
returning buffer to the pool 139,220 
specified in BDAM DCB 66 
specified in BISAM DCB 71 


E 


EBCDIC 
(see extended binary coded decimal 
interchange code) 
ECB 
(see also event control block) 
operand, WAIT macro 217 
ECBLIST operand, WAIT macro 217 
eliminate mode, read column 
BSAM 91,92 
QSAM_ 119,120 
embedded checkpoint records (DOS) 
CNTRL macro 57 
POINT macro 167 
end of data 
(see EODAD operand) 
end of file on magnetic tape, ignoring 
BSAM 97 
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QSAM 125 
end of sequential retrieval 131 
end of volume 
exit 
BSAM 94 
QSAM 123 
forced 133 
entry to 
exit routine 247 
SYNAD routine 240-241 
EODAD operand (DCB macro) 
BPAM 78 
BSAM 94 
QISAM 104 
QSAM_ 122 
EODAD routine 
BSP macro 29 
CHECK macro 39 
FEOV macro 133 
GET macro 143,147 
POINT macro 167 
EROPT operand (DCB macro) 122 
ERP (error recovery procedure for tape) 
BSAM 97 
QSAM 125 
error analysis, I/O 
exception codes 
BDAM 239 
BISAM 236 
QISAM 237 
register contents 
BDAM 241 
BISAM 240 
BPAM 241 
BSAM 241 
QISAM 240 
QSAM 241 
relationship with 
CHECK macro 39 
CNTRL macro 59 
DCB macro 97,125 
GET macro 143,147 
POINT macro 168 
PUT macro 172,174 
PUTX macro 175 
SETL macro 196 
SYNADAF macro 209 
specifying in DCB macro 
BDAM 68 
BISAM 73 
BPAM 81 
BSAM 99 
QISAM 109 
QSAM _ 127 
status indicators 
BDAM 235,242 
BISAM 235 
BPAM 235,242 
BSAM 235,242 
QISAM 235 
QSAM 235,242 
error codes 
(see return codes) 
error conditions while opening a data set 157-158 


error exits 
CHECK macro 39 
CNTRL macro 59 
DCB macro 97,125 
GET macro 147 
POINT macro 168 
PUT macro 172,174 
PUTX macro 175 
SETL macro 196 
SYNADAF macro 209 
error option operand (QSAM) 122 
error recovery procedure for tape 97,125 
error tape, reading 97,125 
ESETL macro instruction 
description 131 
relationship to 
GET macro 143 
SETL macro 195 
event control block 235,265 
exception code 235-239 
exchange buffering 
buffer alignment for 113 
restrictions 
for VS2 systems 114 
record format 114 
track-overflow feature 114,126 
specified in DCB 114 
exclusive control of data block (BDAM) 
releasing of 191 
requesting of 177 
specified in DCB 67 
EXCP macro, relationship with SYNADAF macro 209 
EXCP programming, restriction 197,199 
execute form instructions 
BUILDRCD macro 37 
CHKPT macro 47 
CLOSE macro 55 
OPEN macro 161 
READ macro 189 
SETPRT macro 203 
WRITE macro 231 
exit 
(see also EXLST operand) 
block count 94,123 
data control block 
(see EXLST operand) 
end of data 
(see EODAD operand) 
end of volume 94,123 
error analysis 
(see error analysis, I/O) 
FCB image 94,123 
list format 247 
user labeling 94,123 
user totaling 94,123 
EXLST operand (DCB macro) 
BDAM 65 
BISAM 71 
BPAM 78 
BSAM 94 
list format 247 
QISAM 104-105 
QSAM 123 
expression 
absolute (absexp) 21 
relocatable (relexp) 21 


extended binary coded decimal interchange code (EBCDIC) 
ASCII translation 
Check routine 39 
DCB option 96,125 
GET routine 145 
Put routine 173 
Write routine 223 
XLATE macro 233 
paper tape translation 
BSAM 90 
QSAM 118 
extended search option 
LIMCT operand 65 
OPTCD operand 67 


F 


F-format records 
(see RECFM operand) 
FCB 
image, defining 94,123 
operand (SETPRT macro) 198 
feedback 
block position 177-179,219-220 
next address 178,226 
FEOV macro instruction 133 
file, end of 
(see end of file) 
FIND macro instruction 
description 135-136 
reason codes 136 
return codes 136 
fixed-length records 
(see BLKSIZE operand; RECFM operand) 
format 
exit list 247 
page 169-170 
record 
BDAM 68 
BPAM 80 
BSAM 98-99 
QISAM. 108 
QSAM 126-127 
forms alignment 198 
forms control buffer (FCB) 
image, defining 94,123 
operand (SETPRT macro) 198 
forward space 58 
FREE option with CLOSE macro 50 
FREEBUF macro instruction 
description 137 
relationship to 
BUILD macro 31 
GETBUF macro 149 
FREEDBUF macro instruction 
description 139 
used with BISAM 71,221 
FREEPOOL macro instruction 
description 141 
relationship to 
CLOSE macro 49,141 
GETPOOL macro 141,152 
Friden 8-track paper tape code 
BSAM 90 
QSAM 118 
full-track-index write operation 107 
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fullword boundary alignment 
(see BFAILN operand) 
FUNC operand (DCB macro) 
BSAM 91-92,93 
QSAM_ 119-120,121 


G 


GET macro instruction 
ASCII translation 145 
data mode (QSAM) 124,146 
for 
QISAM 143 
QSAM 145-146 
locate modc 
QISAM 106,143 
QSAM 124,146 
move mode 
QISAM. 106,143 
QSAM 124,146 : 
restriction when using CNTRL macro 57 
restriction when using paper tape 124 
relationship to 
CNTRL macro 57 
EODAD 
(see EODAD operand) 
PDAB macro 163 
RELSE macro 193 
SETL macro 195 
specified in DCB macro 
QISAM 106 
QSAM 124 
substitute mode (QSAM) 124,146 
TYPE=P 145,146 
Get routine exits 143,147 
GETBUF macro instruction 
description 149 
relationship to 
BUILD macro 31 
FREEBUF macro 137 — 
GETPOOL macro instruction 
description 151-152 
relationship to 
BFALN operand 62 
BUFCB operand 63 
BUFL operand 64 
BUFNO operand 64 
FREEPOOL macro 141,152 


I 


IBM BCD perforated tape 
BSAM 90 
QSAM 118 
IHADCB dummy section 129 
IHAPDAB dummy section 165 
image 
FCB (forms control buffer) 94,123,197 
UCS (universal character set) 197-198 
image, data protection 
BSAM 91,93 
QSAM 119,121 
image mode, card 
BSAM 91 
QSAM 119 
independent overflow area, specifying 107 
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index 
cylinder 106 
highest level 
address of 72 
size of 72 
master 
number of tracks per level 106 
specified in OPTCD operand (DCB macro) 107 
space allocation for 101 
indicators, status 235-240 
INOUT open option 156 
input data sets 
closing 49-51 
opening 155-158 
READ or GET specified in DCB 
BDAM 66-67 
BISAM 71-72 
BPAM 79 
BSAM 95-96 
QISAM 106 
QSAM_ 123-124 
reading 
BDAM._ 177-179 
BISAM 181-182 
BPAM 183-184 
BSAM (read a direct data set) 185 
BSAM (read a sequential data set) 183-184 
QISAM 143 
QSAM_ 145-147 
testing completion of I/O operations 
CHECK 39 
WAIT 217-218 
INPUT open option 156 
input/output devices 
card reader and card punch 57 
control of 57-59 
magnetic tape 57 
printer 
CNTRL macro 57-59 
PRTOV macro 169-270 
2540 card punch 115 
3525 card punch 49,57,58,115 
input/output error analysis 
(see SYNAD routine) 
input/output operation 
completion of 39,217-218 
status indicators 235-242 
synchronizing I/O 39,217-218 
interface, DCB 
for BPAM 256-257 
for BSAM 256-257 
for card reader, card punch 255 
for direct-access devices 254 
for magnetic tape 254-255 
for paper tape 255 
for printer 256 
for QSAM 257-258 
interface, logical record 
invoked by BUILDRCD macro 33-34 
provided by QSAM 111,114 
specifying in DCB macro (BFTEK) 114 
used with GET macro 146 
used with PUT macro 174 


ISAM 
general description 69,101 
macro instructions used with 243 
symbolic field names in DCB 259-261 


J 


job control language 
DD statement, relationship to 
CHKPT macro 41 
CLOSE macro 49 
data control block 
(see DDNAME operand) 
GET macro 145 
NOTE macro 153 
OPEN macro 155 
POINT macro 167 
PUT macro 171,173 
LABEL parameter to request ASCII 
translation 39,145,173 
job step checkpoint restart 41 


K 


key, (BDAM) 
dummy 226 
specified in DCB macro 65 
writing 219,225 
key length 
(see KEYLEN operand) 
key position, relative (RKP) 108 
key, record | 
- PUT macro 171 
READ macro 181-182 
RKP operand (DCB macro) 108 
SETL macro 195-196 
WRITE macro 221-222 
KEYLEN operand (DCB macro) 
BDAM 65 _ 
BPAM 78-79 
BSAM 94 
QISAM 105 


L 


label 
(see also EXLST operand) 
exit list format 247 
input data set 125,133,155 
output data set 
CLOSE macro 49 
FEOV macro 133 
OPEN macro 155 
user, processing 94,123 
LABEL parameter in DD statement 39,145,173 
LEAVE option 
CLOSE macro 49 
FEOV macro 133 
OPEN macro 156 
length a 
buffer 
(see BUFL operand) 
record 
(see LRECL operand) 
levels of master index (ISAM) 106 
LIMCT operand (DCB macro) 65-66 


line spacing, printer 
CNTRL macro 57-59 
PRTSP operand (DCB macro) 
BSAM 90 
QSAM 118 
LINK macro, relationship with BLDL macro 27 
list address, data management 55,161 
list form instructions 
BUILDRCD macro 35 
CHKPT macro 45 
CLOSE macro 53 
OPEN macro 159 
READ macro 187 
SETPRT macro 201 
WRITE macro 229 
list format, exit 247 
LOAD macro, relationship with BLDL macro 27 
load mode (QISAM) 101 
loading 
forms control buffer (FCB) 198 
universal character set buffer (UCS) 197 
locate mode 
GET macro 
QISAM 143 
QSAM 146 
PUT macro 
QISAM 171 
QSAM_ 173-174 
specified in DCB macro 
QISAM. 106 
QSAM 124 
logical record length for 
(see also LRECL operand) 
GET macro 145 
PUT macro 171,173 
PUTX macro 175 
LONG operand, WAIT macro 218 
lower limit of sequential retrieval 
(SETL macro) 195-196 
LRECL operand (DCB macro) 
BPAM 79 
BSAM 95 
QISAM 105 
QSAM_ 123 


M 


machine control characters 
BPAM 80 
BSAM 98 
description 249-250 
QSAM 126 
MACREF operand (DCB macro) 
BDAM 66-67 
BISAM 71-72 
BPAM 79 
BSAM 95-96 
QISAM 106 
QSAM 123-124 
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macros, data management 


BLDL 27-28 
BSP 29 
BUILD 31-32 
BUILDRCD 
execute form 37 
list form 35 
standard form 33-34 
CHECK 39 
CHKPT 
execute form 47 
list form 45 
standard form 41-43 
CLOSE 
execute form 55 
listform 53 
standard form 49-51 
CNTRL 57-59 
DCB for 
BDAM 61-68 
BISAM 69-73 
BPAM 75-81 
BSAM 83-99 
QISAM 101-109 
QSAM_ 111-127 
DCBD 129-130 
ESETL 131 
FEOV 133 
FIND 135-136 
FREEBUF 137 
FREEDBUF 139 
FREEPOOL 141 
GET for 
QISAM 143 
QSAM_ 145-147 
GETBUF 149 
GETPOOL 151-152 
NOTE 153 
OPEN 
execute form 161 
list form 159 
standard form 155-158 
PDAB 163 
PDABD 165 
POINT 167-168 
PRTOV 169-170 
PUT for 
QISAM_ 171-172 
QSAM_ 173-174 
PUTX 175 
READ for 
BDAM_ 177-179,185 
BISAM 181-182 
BPAM 183-184 
BSAM_  183-184,185 
execute form 189 
list form 187 
RELEX 191 
RELSE 193 
SETL 195-196 
SETPRT 
execute form 203 
list form 201 
standard form 197-199 
STOW 205-207 
SYNADAF 209-212 
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SYNADRLS 213 
TRUNC 215 
WAIT 217-218 
WRITE for 
BDAM 219-220,225-227 
BISAM 221-222 
BPAM 223-224 
BSAM 223-224,225-227 
execute form 231 
list form 229 
XLATE 233 
macro instruction coding 17-19 
magnetic tape 
backspace 
BSP macro 29 
CNTRL macro 57 
considerations with 
BSP macro 29 
CHKPT macro 41 
CLOSE macro 49,50 
CNTRL macro 57 
POINT macro 167,168 
density .89,117 
end-of-file, ignored 97,125 
final volume positioning (FEOV macro) 133 
forward space 58 
interface in DCB 254-255 
read backward 183 
recording technique 89,117 
restriction when using NOTE macro 153 
restriction when using POINT macro 167 
short error recovery procedure 97,125 
Mass Storage System (see MSS) 
master index 
highest level in storage 
address of storage area 72 
size of storage area 72 
number of tracks per level 106 
option specified in DCB 107 
MAXDCB operand, PDAB macro 163 
member, partitioned data set 
complete a list with BLDL macro 27-28 
locate beginning with FIND macro 135-136 
update directory with STOW macro 205-207 
mode 
(see also MACRF operand) 
card image 
BSAM 91 
QSAM 119 
data (QSAM) 124,146,174 
load (QISAM) 101 
locate 
QISAM 106,143,171 
QSAM_ 146,173 
move 
QISAM 106,143,171 
QSAM 124,146,174 
optical mark read 
BSAM 92 
QSAM 120 
read column eliminate 
BSAM 91,92 
QSAM_ 119,120 
resume load mode 101 
scan (QISAM) 101,106 
substitute (QSAM) 124,146,174 


MODE operand (DCB macro) 
BSAM 91,92 
QSAM._ 119,120 
modifying a parameter list 
BUILDRCD macro 37 
CHKPT macro 47 
CLOSE macro 55 
OPEN macro 161 
READ macro 189 
SETPRT macro 203 
WRITE macro 231 
move mode 
QISAM 143,171 
specified in DCB 106 
QSAM 146,174 
specified in DCB 124 
MSHI operand (DCB macro) 72 
MSS (Mass Storage System) 
device capacity 246 
inDCB 254,259,261 
MSWA operand (DCB macro) 72 
multiline print option 
BSAM 93 
QSAM_ 120 


N 


National Cash Register 8-track paper tape code 
BSAM 90 
QSAM 118 
NCP operand (DCB macro) 
BISAM 72 
BPAM 79 
BSAM 96 
next address feedback 
BDAM (creating) 226 
BDAM (existing) 178 
nonsequential processing of sequential data 83 
NOTE macro instruction 
description 153 
relationship with POINT macro 168 
restriction when using BSP macro 29 
specified in DCB for BSAM 95 
used with BPAM 79 
NTM operand (DCB macro) 106-107 
number of channel programs 
(see NCP operand) 
number of tracks per index level 
(ee NTM operand) 


O 


online printer 
control 57-59 
skipping 169,249-250 
spacing 169,249-250 
OPEN macro instruction 
execute form 161 
list form 159 
relationship to 
CLOSE macro 49 
DDNAME operand 64 
FEOV macro 133 
GETPOOL macro 151 
NOTE macro 153 
POINT macro 167 


READ macro 183 
WRITE macro 223 
standard form 155-158 
open operation, testing 157-158 
open options 156-157 
operand, substitution for 20-21 
OPTCD operand (DCB macro) 
BDAM 67 
BPAM 80 
BSAM 96-97 
QISAM_ 107-108 
QSAM_ 124-125 
SETPRT macro 198 
optical mark read mode 
BSAM 92 
QSAM_ 120 
option codes 
(see OPTCD operand) 
organization, data set 
(see access methods) 
OUTIN open option 156 
output data sets 
closing 49-51 
opening 155-158 
WRITE or PUT specified in DCB macro 
BDAM 66 
BISAM 71-72 
BPAM 79 
BSAM 95-96 
QISAM 106 
QSAM 123-124 
writing 
BDAM 219-220 
BISAM 221-222 
BPAM 223-224 
BSAM 223-224 
BSAM (write to a direct data set) 225-226 
QISAM 171-172 
QSAM_ 173-174 
writing an input record in an output data set 
using PUTX 175 
OUTPUT open option 156 
overflow 
area, independent 107 
channel 169 
exit address (PRTOV macro) 169-170 
printer carriage 169-170 
records 
(see overflow area) 
overflow feature, track 
BDAM 68 
BPAM 80 
BSAM 98 
QSAM 126 
overprinting 169-170 


P 


paper tape codes 
BSAM 90 
QSAM 118 

parallel data access block (PDAB) 
constructing 163 
generating a DSECT 165 
symbolic field names 267 
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parameter list construction 
BUILDRCD macro 35 
CHKPT macro 45 
CLOSE macro 53 
OPEN macro 159 
READ macro 187 
SETPRT macro 201 
WRITE macro 229 
parameter list, modification 
BUILDRCD macro 37 
CHKPT macro 47 
CLOSE macro 55 
OPEN macro 161 
READ macro 189 
SETPRT macro 203 
WRITE macro 231 
partitioned data set 
general description 75 
macro instructions used with 243 
relationship to 
BLDL macro 27 
FIND macro 135 
STOW macro 205 
PDAB macro instruction 163 
PDABD 
macro instruction 165 
symbolic field names 267 
POINT macro instruction 
description 167-168 
relationship to 
BSAM 83 
NOTE macro 153 
restriction 
with BSP macro 29 
specified in MACRF operand 
BPAM 79 
BSAM 95 
position, relative key (RKP) 108 
position feedback 
current block 177-179,219-220 
next block 178,226 
positioning volumes 
using CLOSE macro 49-51 
using FEOV macro 133 
using OPEN macro 155-158 
prefix, block 
BSAM 87 
QSAM 116 
relationship to 
buffer length 87,115 
data alignment 85,113 
print options (3747) 
BSAM 91,93 
QSAM 119,121 
printer 
carriage control 57-59,169-170 
character set buffer loading 197-198 
control characters 249-250 
control tape 169-170 
forms control buffer loading 198 
skipping 57-59,249-250 
spacing 57-59,249-250 
program, channel 
BISAM 72 
BPAM 79 
BSAM 96 
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protection option, data 
BSAM 91,93 
QSAM 119,121 
PRTOV macro instruction 169-170 
PRTSP operand (DCB macro) 
BSAM 90 
QSAM 118 
punch, card 91,119 
PUT macro instruction 
data mode (QSAM) 124,174 
for 
QISAM 171-172 
QSAM_ 173-174 
locate mode 
QISAM 171 
QSAM_ 173-174 
move mode 
QISAM 171 
QSAM_ 174 
relationship with 
PRTOV macro 169 
SYNADAF macro 209 
TRUNC macro 215 
specified in DCB macro 
QISAM 106 
QSAM 124 
substitute mode (QSAM) 174 
PUTX macro instruction 175 
output mode 175 
relationship with TRUNC macro 215 
specified in DCB macro 
QISAM 106 
QSAM 124 
update mode 175 


Q 


QISAM (queued indexed sequential access method) 
general description 101 
macro instructions used with 243 
symbolic field names in DCB 259-261 
QSAM (queued sequential access method) 
general description 111 
macro instructions used with 243 
symbolic field names in DCB 252-258 
queued access technique 
(see QISAM and QSAM) 


R 


RDBACK open option 156 
read backward, magnetic tape 156,183 
read column eliminate mode 
BSAM 91,92 
QSAM_ 119,120 
READ macro instruction 
execute form 189 
for 
BDAM_ 177-179,185 
BISAM 181-182 
BPAM 183-184 
BSAM_183-184,185 
list form 187 


READ macro instruction (continued) 
relationship to 
BFTEK operand 63 
BUFL operand 64 
CHECK macro 39 
EODAD operand 78,94 
FIND macro 135 
FREEDBUF macro 139 
KEYLEN operand 65 
LIMCT operand 65-66 
MACRF operand 66-67 
NCP operand 
BISAM 72 
BPAM 79 
BSAM 96 
OPTCD operand 67 
POINT macro 167 
RELEX macro 191 
WAIT macro 217 
WRITE macro 220,221,223 
specified in DCB macro 
BDAM 66-67 
BISAM 71-72 
BPAM 79 
BSAM 95-96 
standard form 
BDAM_ 177-179 
BISAM 181-182 
BPAM 183-184 
BSAM (read direct data set) 185 
BSAM (read sequential data set) 183-184 
reason codes 
BLDL macro 28 
BSP macro 29 
FIND macro 136 
STOW macro 207 
RECFM operand (DCB macro) 
BDAM 68 
BPAM 80 
BSAM 98-99 
QISAM 108 
QSAM_ 126-127 
record 
area 
construction 33-34 
deletion option (ISAM) 107 
format 
(see RECFM operand) 
length 
(see LRECL operand) 
logical 
GET 143,145 
PUT 171,173 
descriptor word, relationship with 
BLKSIZE operand 103 
BUFOFF operand 87 
LRECL operand 95,105,123 
physical 
(see BLKSIZE operand) 
retrieval 143,145,177-185 
segment 173 
variable-length, spanned 33,114 
writing 171-174,219-227 
recording density, magnetic tape 
BSAM 89 
QSAM 117 


recording technique, magnetic tape 
BSAM 89 
QSAM 117 
register 
contents on entry to 
DCB exit routine 247 
overflow exit routine 169-170 
SYNAD routine 240-241 
DCBD base 129-130 
usage rules 22 
relative addressing 
BDAM 61,67 
BLDL macro 27-28 
FIND macro 135-136 
POINT macro 167-168 
relative key position 108 
release 
buffer 137 
buffer pool 141 
dynamically acquired buffer 139 
exclusive control 191 
QSAM buffer 193 
QSAM buffer 193 
RELEX macro instruction 
description 191 
relationship to MACRF operand 67 
return codes 191 
relexp defined 21 
relocatable expression defined 21 
RELSE macro instruction 193 
reorganization statistics (ISAM) 101,107 
REREAD option 
CLOSE macro 49 
FEOV macro 133 
OPEN macro 156 
restart job from a checkpoint 
automatic 41 
deferred 41 
restore data control block 49 
resume load mode 101 
return codes 
BLDL macro 28 
BSP macro 29 
CHKPT macro 43 
FIND macro 136 
RELEX macro 191 
SETPRT macro 199 
STOW macro 207 
SYNADAF macro 211 
SYNADRLS macro 213 
WRITE macro 227 , 
RETURN macro, relationship with SYNAD operand 
BDAM 68 
BISAM 73 
BPAM 81 
BSAM 99 
QISAM_ 109 
QSAM 127 
REWIND option 
CLOSE macro 49 
FEOV macro 133 
RKP operand (DCB macro) 108 
relationship with LRECL operand 105 
RO (see capacity record) 
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S 


Save area 
general register requirements 22 
SYNADAF requirement 209 
SYNADRLS macro 213 

scan mode 101,106 

search 
partitioned data set directory 

BLDL macro 27 

FIND macro 135 
type of 

BDAM 219-220 

QISAM 106 

search argument 
BDAM 66 
QISAM 106 

search direct option 97,125 

search option, extended 67 

segment 
buffer 171 
descriptor word 86,185 
work area 64 

sequential access methods 
(see access methods) 

services, optional 
BDAM 67 
BPAM 80 
BSAM 96-97 
QISAM 107-108 
QSAM_ 124-125 
SETPRT macro 198 

SETL macro instruction 
description 195-196 
relationship to 

ESETL macro 131 
GET macro 143 

SETPRT macro instruction 
execute form 203 
list form > 201 
return codes 198 
standard form 197-199 

simple buffering 114 

skipping, printer 
(see also spacing, printer) 
CNTRL macro 57-58 
control characters 249-250 

SMSI operand (DCB macro) 72-73 

SMSW operand (DCB macro) 73 

space, magnetic tape 
backward 27,57 
forward 57 

space allocation, data set 
BPAM 75 
QISAM 101 

spacing, printer 
(see also skipping, printer) 
CNTRL macro 57-59 
control characters 249-250 
specified in DCB macro 

BSAM 90 
QSAM 118 

STACK operand (DCB macro) 
BSAM 91,93 
QSAM 119,121 
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stacker selection 
CNTRL macro 57-58 
control characters 249-250 
specified in DCB macro 
BSAM 91,93 
QSAM 119,121 
statistics reorganization (ISAM) 101,107 
Status 
following an I/O operation 235-242 
indicators 242 
STOW macro instruction 
description 205-207 
directory action 206 
reason codes 207 
return codes 207 
substitute mode 
GET macro 146 
PUT macro 174 
specified in DCB macro 124 
switching volumes 
CHECK macro 39 
CLOSE macro 49 
FEOV macro 133 
symbol defined 20 
SYNAD operand (DCB macro) 
BDAM 68 
BISAM 73 
BPAM 81 
BSAM 99 
QISAM 109 
QSAM 127 
SYNAD routine 
exception codes 
BDAM 239 
BISAM 236 
QISAM 237 
register contents 
BDAM 241 
BISAM 240 
BPAM 241 
BSAM 241 
QISAM 240 
QSAM 241 
relationship with 
CHECK macro 39 
CNTRL macro 59 
DCB macro 97,125 
GET macro 143,147 
POINT macro 168 
PUT macro 172,174 
PUTX macro 175 
SETL macro 196 
SYNADAF macro 209 
specifying in DCB macro 
BDAM 68 
BISAM 73 
BPAM 81 
BSAM 99 
QISAM 109 
QSAM_ 127 


SYNAD routine (continued) 
status indicators 
BDAM 235,242 
BISAM 235 
BPAM 235,242 
BSAM 235,242 
QISAM 235 
QSAM 235,242 
SYNADAF macro instruction 
description 209-212 
relationship with SYNADRLS macro 213 
return codes 211 
SYNADRLS macro instruction 213 
relationship with SYNADAF macro 209 
synchronizing I/O operations 39,217-218 
synchronous error exit 
(see SYNAD operand) 
SYSIN restrictions 
BSP macro 29 
CLOSE macro 49 
CNTRL macro 57 
DEVD operand (DCB macro) 
BSAM 88 
QSAM 116 
FEOV macro 133 
MACREF operand 95 
NOTE macro 153 
OPEN macro 155 
OPTCD operand 97,125 
POINT macro 168 
PUTX macro 175 
RECFM operand 99,126 
RELSE macro 193 
SYSOUT restrictions 
BSP macro 29 
CLOSE macro 49 
CNTRL macro 57 
FEOV macro 133 
MACREF operand 95 
NOTE macro 153 
OPEN macro 155 
OPTCD operand 97,125 
POINT macro 168 
PUTX macro 175 


T 


tape codes, paper 
BSAM 90 
QSAM 118 
tape density, magnetic 
BSAM 89 
QSAM 117 
tape error recovery procedure 
BSAM 97 
QSAM 125 
tape recording technique 
BSAM 89 
QSAM 117 
Teletype 5-track paper tape code 
BSAM 90 
QSAM 118 
temporary close of dataset 49-51 


termination, abnormal 
Check routine 39 
end of data 
(see EODAD operand) 
uncorrectable I/O error 
(see SYNAD operand) 
testing completion of I/O 39,217 
testing for open data set 157-158 
totaling exit, user 
BSAM 94 
list format 247 
QSAM_ 123 
track addressing, relative 
BDAM 61,67 
BLDL macro 27-28 
FIND macro 135-136 
POINT macro 167-168 
track index write, full 107 
track-overflow feature 
BDAM 68 
BPAM 80 
BSAM 98 
QSAM 126 
restrictions 
chained scheduling 80,126 
exchange buffering 114,126 
ISAM 101 
translation 
ASCII to EBBCDIC 
CHECK macro 39 
GET macro 145 
XLATE macro 233 
EBCDIC to ASCII 
PUT macro 173 
WRITE macro 223 
XLATE macro 233 
paper tape code 90,118 
transmittal modes 
(see also MACRF operand) 
data 124,146 
locate 143,146,171,174 
move 143,146,171,174 
specifying 106,124 
substitute 146,174 
TRTCH operand (DCB macro) 
BSAM 89 
QSAM 117 
TRUNC macro instruction 215 
specified in QSAM DCB 124 
truncating a block 215 
TYPE=P (GET macro) 147 
TYPE=T (CLOSE macro) 49-51 


U 


U-format records 
BDAM 68 
BPAM 80 
BSAM 98 
QSAM 126 
UCS feature 
unblocking data checks 97,125 
UCS operand (SETPRT macro) 197-198 
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unblocking data checks 
BSAM 97 
QSAM. 125 
SETPRT macro 197 
uncorrectable I/O errors 
(see SYNAD operand) 
undefined length records 
(see U-format records) 
universal character set 
(see UCS operand) 
unmovable data sets 
(see DSORG operand) 
UPDAT open option 156 
updating partitioned data set directory 205-207 
user 
data in partitioned data set directory 
BLDL macro 27-28 
STOW macro 205-207 
label exit 
BSAM 94 
list format 247 
QSAM_ 123 
totaling exit 
BSAM 94 
list format 247 
QSAM 123 
USING statement requirement 
DCBD macro 129 
PDABD macro 165 


V 


V-format records 

BDAM 68 

BPAM 80 

BSAM 98 

QISAM 108 

QSAM 126 
validity checking, write 

BDAM 67 

BPAM 80 

BSAM 97 

QISAM 107 

QSAM_ 125 
variable-length, spanned records 

(see also V-format records) 

BDAM 62-63,225 

BSAM 86,225 

QSAM 114,173 

restriction with FEOV 133 

restriction with GET 145 
variable-length records 

(see V-format records) 
volume, forcing end of 133 
volume positioning 

CHECK macro 39 

CLOSE macro 49-51 

FEOV macro 133 

OPEN macro 155-158 

POINT macro 167-168 
volume switching 39 
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WwW 


WAIT macro instruction 
description 217-218 
relationship to 

MACREF operand 66 
READ macro 177,181 
WRITE macro 219,221 
work area for BISAM 
address of 72 
size of 72 

WRITE macro instruction 
execute form 231 
list form 229 
relationship to 

BUFL operand 64 
CHECK macro 39 
KEYLEN operand 65 
LIMCT operand 65-66 
MACREF operand 66,67 
NCP operand 
BISAM 72 
BPAM 79 
BSAM 96 
OPTCD operand 67 
POINT macro 167 
PRTOV macro 169 
READ macro 181 
RELEX macro 191 
SYNADAF macro 209 
WAIT macro 217 
specified in DCB macro 
BDAM 66 
BISAM 72 
BPAM 79 
BSAM 96 
standard form 
BDAM (create with BSAM) 225-227 
BDAM (existing) 219-220 
BISAM 221-222 
BPAM 223-224 
BSAM 223-224 
testing for completion 39,217-218 


WTOR macro, relationship with SETPRT macro 198 


X 


XCTL macro, relationship with BLDL macro 27 
XLATE macro instruction 233 
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